TraconId

Namespace Tracon · Assembly Tracon.Abstractions.dll

UUID version 7 generator for Tracon identifiers (RFC 9562).

public static class TraconId

Inheritance

object ← TraconId

Inherited Members

object.GetType(), object.MemberwiseClone(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

A UUIDv7 is time ordered: the first 48 bits are a Unix millisecond stamp. This keeps B-tree indexes from fragmenting and makes ORDER BY id return time order. It also avoids the central sequence bottleneck of bigserial.

We use our own implementation instead of Guid.CreateVersion7 from.NET 9. The reason: the package also targets net8.0, and storage keys must be produced the same way on every target.

Methods

DeriveId(DateTimeOffset, string)

Creates a UUIDv7 that depends only on its inputs: the same time stamp and seed always produce the same identifier.

public static Guid DeriveId(DateTimeOffset timestamp, string seed)

Parameters

timestamp DateTimeOffset

The time stamp to embed. Must itself be stable across calls — a stored creation time, never DateTimeOffset.UtcNow.

seed string

The value the identifier is derived from.

Returns

Guid

A time-ordered identifier that can be recomputed.

Remarks

For a write that must be re-drivable after a crash. Where TraconId.NewId would mint a second identifier on a retry — and so a second row — a derived one lets the retry land on exactly the row the interrupted attempt was creating, without a table to remember what that row was going to be.

Still a real UUIDv7, so it keeps the index locality TraconId.NewId is chosen for: only the random bytes are replaced, by a SHA-256 digest of seed. It is a derivation, not a signature — the seed is not recoverable, but neither is it a secret.

GetTimestamp(Guid)

Reads the time stamp back out of a UUIDv7.

public static DateTimeOffset GetTimestamp(Guid id)

Parameters

id Guid

The UUIDv7 value.

Returns

DateTimeOffset

The time stamp embedded in the identifier.

Exceptions

ArgumentException

id is not a version 7 value.

NewId()

Creates a new UUIDv7 stamped with the current time.

public static Guid NewId()

Returns

Guid

A time-ordered identifier.

NewId(DateTimeOffset)

Creates a UUIDv7 stamped with the given time.

public static Guid NewId(DateTimeOffset timestamp)

Parameters

timestamp DateTimeOffset

The time stamp to embed in the identifier.

Returns

Guid

A time-ordered identifier.