SequentialGuid.EntityFrameworkCore 6.2.0

SequentialGuid.EntityFrameworkCore

EF Core value-converter support for the SequentialGuid library. Register once and Entity Framework Core can automatically persist SequentialGuid and SequentialSqlGuid properties as standard Guid database columns.

Install

dotnet add package SequentialGuid.EntityFrameworkCore

Supported Frameworks

Setup

Register the value converters in your DbContext by overriding ConfigureConventions:

using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
    {
        // Registers converters for both SequentialGuid and SequentialSqlGuid
        configurationBuilder.AddSequentialGuidValueConverters();
    }
}

This single call registers value converters for both SequentialGuid and SequentialSqlGuid so that any entity property of either type is transparently converted to and from Guid when reading/writing to the database.

Entity Model Example

using SequentialGuid;

public class Order
{
    // Assigned at construction - no database round-trip needed
    public SequentialGuid Id { get; set; } = new();

    // Timestamp is always available from the ID itself
    public DateTime? CreatedAt => Id.Timestamp;

    public string Description { get; set; } = string.Empty;
}

If you are targeting SQL Server and want IDs that sort correctly in uniqueidentifier columns, use SequentialSqlGuid instead:

public class Order
{
    public SequentialSqlGuid Id { get; set; } = new();
}

How It Works

Under the hood, SequentialGuidValueConverter<T> (where T : struct, ISequentialGuid<T>) converts:

• To database: extracts the underlying Guid via value.Value
• From database: reconstructs the struct via T.Create(guid), which validates the GUID is a recognized sequential format

This means the database column type remains a standard Guid / uniqueidentifier - no schema changes are needed.

JSON Serialization

If your API returns entities containing SequentialGuid / SequentialSqlGuid properties, register the built-in JSON converters in your Program.cs:

using SequentialGuid.Extensions;

builder.Services.AddControllers()
    .AddJsonOptions(o => o.JsonSerializerOptions.AddSequentialGuidConverters());

Value generation

UseSequentialGuidValueGeneration() registers a model-finalizing convention that assigns RFC 9562 v7 sequential value generators to every Guid, SequentialGuid, and SequentialSqlGuid primary-key property. Keys are generated client-side on Add — no database round-trip, retry-safe.

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.AddSequentialGuidValueConverters();
    configurationBuilder.UseSequentialGuidValueGeneration();           // v7 keys on Add
    // configurationBuilder.UseSequentialGuidValueGeneration(sqlServerByteOrder: true);
}

• Plain Guid keys get standard byte order; pass sqlServerByteOrder: true to switch to SQL Server uniqueidentifier-friendly order.
• SequentialGuid / SequentialSqlGuid keys carry byte order in the type and ignore the flag.
• Explicit HasValueGenerator<T>() always wins — the convention never overwrites it.
• The four generators (SequentialGuidValueGenerator, SequentialSqlGuidValueGenerator, SequentialGuidStructValueGenerator, SequentialSqlGuidStructValueGenerator) are public for explicit per-property wiring.

Further Reading

See the main SequentialGuid README for full documentation on UUID generation, timestamp extraction, and SQL Server byte-order handling.