Class UuidV7Generator

Namespace

Xapi

Assembly

Xapi.Core.dll

Generates RFC 9562 version 7 UUIDs that are strictly increasing per generator, also within the same millisecond. Use them as statement ids and as time-ordered storage keys.

public sealed class UuidV7Generator

Inheritance

object

UuidV7Generator

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Layout (RFC 9562, 6.2 method 1, fixed-length dedicated counter): 48-bit Unix time in milliseconds, version 7, then a 42-bit counter spread over rand_a and the top of rand_b, then 32 random bits. A new millisecond reseeds the counter with a random value whose top bit is clear, leaving room to increment. If the counter overflows, or the clock goes backwards, the timestamp field moves forward by one millisecond so the ordering never breaks.

Guid.CreateVersion7() on .NET 9+ fills the same bits randomly, so ids created in one millisecond do not sort in creation order; this generator exists for that reason and also runs on netstandard2.0. The ordering holds for the canonical string form and for big-endian bytes, not for ToByteArray().

Constructors

UuidV7Generator()

Creates a generator that reads the system clock.

public UuidV7Generator()

UuidV7Generator(Func<DateTimeOffset>)

Creates a generator that reads the given clock.

public UuidV7Generator(Func<DateTimeOffset> clock)

Parameters

clock Func<DateTimeOffset>

Returns the current time.

Properties

Shared

A process-wide generator using the system clock. Thread-safe.

public static UuidV7Generator Shared { get; }

Property Value

UuidV7Generator

Methods

GetTimestamp(Guid)

Reads the Unix millisecond timestamp stored in a version 7 UUID.

public static DateTimeOffset GetTimestamp(Guid uuid)

Parameters

uuid Guid

A version 7 UUID.

Returns

DateTimeOffset

The embedded time, in UTC.

Exceptions

ArgumentException

uuid is not a version 7 UUID.

NewGuid()

Creates the next UUID. Thread-safe.

public Guid NewGuid()

Returns

Guid

A version 7, variant 2 UUID greater than every UUID this generator returned before.