SequentialGuid 6.2.0

SequentialGuid

👁 Continuous Integration
👁 NuGet
👁 NuGet Downloads
👁 License: MIT

Generate database-friendly, time-ordered UUIDs anywhere in your stack — no database round-trip required.

SequentialGuid is a zero-dependency .NET library that produces RFC 9562 compliant UUIDs. Generate IDs in Blazor WebAssembly, MAUI, a background worker, or a REST controller — then pass them through your API and into the database. Because the timestamp is embedded in the value itself, you get natural sort order (dramatically reducing clustered index fragmentation), built-in timestamp extraction (no extra CreatedAt column needed), and client-side idempotency (retry-safe inserts without a server round-trip to generate a key).

Why not just use Guid.NewGuid()?

Guid.NewGuid() produces random version 4 UUIDs. They work, but they fragment clustered indexes in SQL Server, PostgreSQL, and other B-tree based stores because every insert lands at a random page. SequentialGuid solves this by putting the timestamp first — new rows always append near the end of the index, just like an auto-increment integer, while still giving you the global uniqueness and merge-safety of a UUID.

UUID Versions at a Glance

Highlights

• RFC 9562 compliant — correct version nibble and variant bits on every UUID, every time
• Monotonically increasing — GuidV7 and GuidV8Time both use a process-global Interlocked.Increment counter so IDs generated on the same timestamp are still strictly ordered, even under heavy concurrency
• Zero dependencies — the core package references nothing outside the BCL
• Zero allocations on modern .NET — stackalloc, Span<T>, and [SkipLocalsInit] eliminate heap allocations on every generation path on the package's .NET 10 / 9 / 8 targets, including the deterministic v5/v8 name-based generators
• Broad platform support — targets .NET 10 / 9 / 8, .NET Framework 4.6.2, and .NET Standard 2.0, with explicit browser platform support and Native AOT compatibility for Blazor WebAssembly
• Native AOT compatible — declares IsAotCompatible=true and is verified end-to-end with a published AOT smoke test in CI
• Round-trip timestamp extraction — call .ToDateTime() on any Guid (V7, V8, or legacy) to recover the embedded UTC timestamp — works on SqlGuid too
• SQL Server sort-order aware — NewSqlGuid() and .ToSqlGuid() / .FromSqlGuid() handle the byte-order shuffle so your UUIDs sort chronologically in uniqueidentifier columns — the only production use of System.Data.SqlTypes.SqlGuid is inside SequentialSqlGuid.CompareTo, where it implements SQL Server's documented sort order
• Built-in benchmarks — a BenchmarkDotNet project is included so you can measure generation and conversion performance on your own hardware

GuidV7 vs GuidV8Time — Which Should I Use?

Both generate time-ordered, sortable UUIDs. The difference is timestamp resolution and payload:

Rule of thumb: Start with GuidV7. Reach for GuidV8Time only when you need tick-level precision or the machine/process fingerprint.

GuidV5 vs GuidV8Name

Both produce deterministic UUIDs from a namespace + name pair. The only difference is the hash algorithm:

• GuidV5 — Uses SHA-1 as required by RFC 9562 §5.5. Choose this when you need interoperability with UUIDv5 implementations in other languages.
• GuidV8Name — Uses SHA-256 as described in RFC 9562 Appendix B.2, providing a stronger hash for .NET-only scenarios.

Quick Start

Install

dotnet add package SequentialGuid

Generate a time-ordered UUID

using SequentialGuid;

// Millisecond precision (RFC 9562 UUIDv7) — recommended for most applications
var id = GuidV7.NewGuid();

// Sub-millisecond / tick precision (RFC 9562 UUIDv8)
var id = GuidV8Time.NewGuid();

Generate a SQL Server-friendly UUID

Both time-based generators provide a NewSqlGuid() method that rearranges the byte order to match SQL Server's uniqueidentifier sorting rules:

var sqlId = GuidV7.NewSqlGuid();
// or
var sqlId = GuidV8Time.NewSqlGuid();

Generate a random UUID (V4)

// Guaranteed RFC 9562 version & variant bits (unlike Guid.NewGuid() on some runtimes)
var id = GuidV4.NewGuid();

Generate a deterministic UUID from a namespace + name

// SHA-1 (UUIDv5) — interoperable with other languages
var id = GuidV5.Create(GuidV5.Namespaces.Url, "https://example.com");

// SHA-256 (UUIDv8 name-based) — stronger hash, .NET only
var id = GuidV8Name.Create(GuidV8Name.Namespaces.Url, "https://example.com");

Extract the timestamp from any time-based UUID

DateTime? created = id.ToDateTime();
// Works on GuidV7, GuidV8Time, legacy SequentialGuid, and even SqlGuid values

Helpers for common timestamp & predicate scenarios

// Try-pattern variant — useful when you want to branch without nullable handling
if (id.TryToDateTime(out var created))
{
 Console.WriteLine($"Created at {created:O}");
}

// DateTimeOffset variant — explicit UTC offset
DateTimeOffset? createdOffset = id.ToDateTimeOffset();

// Predicate — "is this a recognised sequential GUID at all?"
bool isOurs = someGuid.IsSequentialGuid();

// RFC 9562 §5.10 max UUID constant — useful for range-scan upper bounds
Guid upper = Guid.MaxValue;

Convert between Guid and SqlGuid byte order

var guid = GuidV7.NewGuid();
var sqlGuid = guid.ToSqlGuid(); // reorder bytes for SQL Server
var back = sqlGuid.FromSqlGuid(); // restore standard byte order

Stamp a timestamp from an existing DateTime / DateTimeOffset

var id = GuidV7.NewGuid(DateTimeOffset.UtcNow);
var id = GuidV8Time.NewGuid(DateTime.UtcNow);

Dependency injection example

public interface IIdGenerator
{
 Guid NewId();
}

public class SequentialIdGenerator : IIdGenerator
{
 public Guid NewId() => GuidV7.NewGuid();
}

// In your startup / Program.cs
services.AddTransient<IIdGenerator, SequentialIdGenerator>();

Base entity example

public abstract class BaseEntity
{
 // ID is assigned at construction — no database round-trip needed
 public Guid Id { get; set; } = GuidV7.NewGuid();

 // Timestamp is always available — no extra column required
 public DateTime? CreatedAt => Id.ToDateTime();
}

SQL Server Sorting

SQL Server sorts uniqueidentifier values in a non-obvious byte order. If you use SQL Server, read these two articles to understand the implications:

• Comparing GUID and uniqueidentifier Values
• How are GUIDs sorted by SQL Server?

Use the NewSqlGuid() methods (or the .ToSqlGuid() extension) to produce UUIDs whose byte order aligns with SQL Server's comparison logic. The .FromSqlGuid() extension on Guid reverses the transformation — the name clearly conveys the intent of converting from SQL Server byte order back to the standard layout.

Strongly-Typed Struct Wrappers

The library ships two readonly record struct types — SequentialGuid and SequentialSqlGuid — that wrap a Guid and guarantee at construction time that the value is a valid sequential UUID. They both implement ISequentialGuid<TSelf> which provides IComparable, IComparable<TSelf>, IEquatable<TSelf>, IFormattable / ISpanFormattable / ISpanParsable<T> / IUtf8SpanFormattable / IUtf8SpanParsable<T> (where available), and comparison operators.

Creating struct instances

using SequentialGuid;

// Generate a new V7 UUID (default)
var id = new SequentialGuid();

// Generate a new V8 UUID
var id = new SequentialGuid(SequentialGuidType.Rfc9562V8Custom);

// Wrap an existing Guid (validates it is a sequential UUID)
var id = new SequentialGuid(existingGuid);

// Parse from a string
var id = new SequentialGuid("01234567-89ab-7def-8000-0123456789ab");

SQL Server variant:

var sqlId = new SequentialSqlGuid();
var sqlId = new SequentialSqlGuid(SequentialGuidType.Rfc9562V8Custom);
var sqlId = new SequentialSqlGuid(existingGuid); // auto-detects byte order

Properties

Guid raw = id.Value; // the underlying Guid
DateTime utc = id.Timestamp; // the embedded UTC timestamp

Comparison & equality

The structs support <, <=, >, >=, ==, and != operators, plus CompareTo and Equals:

var a = new SequentialGuid();
var b = new SequentialGuid();
bool isNewer = b > a; // true — b was created after a

// Also comparable directly against Guid
bool same = a.Equals(a.Value); // true

JSON serialization (System.Text.Json)

On .NET 7+ the library includes built-in JsonConverter<T> support. Register the converters once:

using SequentialGuid.Extensions;

var options = new JsonSerializerOptions();
options.AddSequentialGuidConverters();

// Now SequentialGuid / SequentialSqlGuid serialize as GUID strings automatically
var json = JsonSerializer.Serialize(new SequentialGuid(), options);

Parsing

// Parse (throws on invalid input)
var id = SequentialGuid.Parse("01234567-89ab-7def-8000-0123456789ab");

// TryParse (returns false on invalid input)
if (SequentialGuid.TryParse(input, out var parsed))
{
 // use parsed
}

Companion Packages

Performance

On modern .NET the hot paths are zero-allocation — byte buffers use stackalloc and Span<T>, and conversion methods are annotated with [SkipLocalsInit]. A BenchmarkDotNet project is included under util/Benchmarks so you can verify on your own hardware:

cd util/Benchmarks
dotnet run -c Release -- --filter *Generation*

Backwards Compatibility

The new RFC 9562 algorithm is fully backwards compatible with previously generated Guids:

• Sort order is preserved — All UUIDs generated with the legacy algorithm will sort before any UUIDs generated with the new algorithm in the database, so existing data ordering is unaffected.
• Timestamp extraction still works — The ToDateTime() extension method can extract timestamps from both legacy and new UUIDs, so you do not need to migrate existing data.