FastIDs.TypeId.EntityFramework 1.0.0

FastIDs.TypeId.EntityFramework

Entity Framework Core integration for FastIDs.TypeId: value converters, a model convention and client-side value generators for TypeId and TypeIdDecoded.

Requires EF Core 8.0 or later.

Installation

dotnet add package FastIDs.TypeId.EntityFramework

Quick start

Register the convention once. Every TypeId / TypeIdDecoded property (nullable ones too) in the model is then mapped to a varchar(90)-like column automatically:

using FastIDs.TypeId;
using FastIDs.TypeId.EntityFramework;

public class MyContext : DbContext
{
    public DbSet<User> Users => Set<User>();

    protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
        => configurationBuilder.ConfigureForTypeId();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
        => modelBuilder.Entity<User>().Property(u => u.Id).HasTypeIdGenerator("user");
}

public class User
{
    public TypeId Id { get; set; }
    public string Name { get; set; } = "";
}

HasTypeIdGenerator("user") generates a new UUIDv7-based ID on the client whenever an entity with a default Id is added, so context.Users.Add(new User { Name = "Ann" }) just works.

Storage options

Mix them freely, the property-level mapping wins over the convention:

modelBuilder.Entity<Order>().Property(o => o.Id)
    .HasTypeIdGuidConversion("order")
    .HasTypeIdGenerator("order");

You can also configure a property with the converters directly: TypeIdToStringConverter, TypeIdDecodedToStringConverter, TypeIdToGuidConverter, TypeIdDecodedToGuidConverter. Always pair them with the matching comparer (TypeIdValueComparer / TypeIdDecodedValueComparer):

modelBuilder.Entity<User>().Property(u => u.Id)
    .HasConversion<TypeIdToStringConverter, TypeIdValueComparer>();

EF Core hashes default values (for example a foreign key that isn't populated yet while an entity graph is attached), and default(TypeId).GetHashCode() throws. TypeIdValueComparer handles it. ConfigureForTypeId and HasTypeIdGuidConversion register the comparers for you.

Which one to use?

• The string mapping is the safest default: self-describing values, any type in any column, works on every provider. TypeId is the cheapest type to use with it because converting it to and from a string doesn't allocate.
• Prefer the UUID mapping when you have a single type per column and care about index size and insert speed. UUIDv7 is time-ordered, which keeps B-tree inserts append-mostly on PostgreSQL and MySQL. SQL Server sorts uniqueidentifier values in a different byte order, so IDs are not sorted by creation time there.
• String columns are compared using the database collation. If you sort or range-query by a string TypeId column, use a binary/ordinal collation to get ordinal ordering consistent with TypeId.CompareTo.

Limitations

• Compiled models (dotnet ef dbcontext optimize) and the EF Core features built on them (precompiled queries, Native AOT) are not supported yet. The compiled model generator can't emit C# literals for the TypeId / TypeIdDecoded structs, and per-property settings that take the TypeId type (HasTypeIdGenerator, HasTypeIdGuidConversion) can't be expressed by type, which the generator requires.
• A GUID column doesn't store the TypeId type, so every value written must have the type configured in the mapping.