Entity Configuration

The Problem

EF Core needs to know how to map your entities to the database: which property is the primary key, which properties need indexes, how relationships are configured, what the column types should be. Without configuration, EF Core guesses — and sometimes guesses wrong.

Writing IEntityTypeConfiguration<T> for each entity is repetitive: every entity needs a primary key on PersistenceId, every [LogicKey] property needs a unique index, every [SoftDelete] entity needs a query filter.

The Solution

The source generator produces a complete IEntityTypeConfiguration<T> for each entity, based on the attributes you’ve declared.

// ═══ Generated: EntityConfig.{Namespace}.Order.g.cs ═══
internal sealed class OrderEntityConfig : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders");                       // the type name, pluralised
        builder.HasKey(e => e.PersistenceId);

        // A Guid key is assigned by the trait at construction, so the store must not claim it
        builder.Property(e => e.PersistenceId).ValueGeneratedNever();

        // [LogicKey] → unique index
        builder.HasIndex(e => e.OrderNumber).IsUnique();

        // private set → EF writes the field, not the property
        builder.Property(e => e.OrderNumber).UsePropertyAccessMode(PropertyAccessMode.Field).IsRequired();

        // [SoftDelete] → a *named* EF query filter, plus an index on the flag
        builder.HasQueryFilter("SoftDelete", e => !e.IsDeleted);
        builder.HasIndex(e => e.IsDeleted);

        // [Relation.OneToMany<LineItem>] declared on the parent → Cascade
        builder.HasMany(e => e.LineItems)
            .WithOne(e => e.Order)
            .OnDelete(DeleteBehavior.Cascade);
    }
}

Three things that are not in there:

• The concurrency token. [ConcurrencyAware] produces a shadow property, declared in the generated DbContext and shaped by the provider — there is no e.RowVersion to configure.
• The audit fields. [Auditable] adds the four properties to the entity; nothing configures them here, so they take EF’s conventions.
• The filtered unique index. On a [SoftDelete] entity the logic-key index has to exclude deleted rows, or a re-insert with the same key fails. That filter is raw provider SQL, so it is emitted in the DbContext where the provider is known: modelBuilder.Entity<Order>().HasIndex(e => e.OrderNumber).IsUnique().HasFilter("\"IsDeleted\" = 0").

Property Mapping Rules

The SG applies these rules when generating property configuration:

C# Type	Generated Configuration	Notes
string	.IsRequired() if not nullable	.HasMaxLength(n) if [MaxLength(n)] present
decimal	.HasPrecision(18, 2)	Default precision for monetary values
byte[] (RowVersion)	.IsRowVersion()	Only for [ConcurrencyAware] entities
enum	Stored as int	Default EF Core behavior
DateTimeOffset	.IsRequired() if not nullable	Audit fields: CreatedAt is required, UpdatedAt is optional

Relationship Configuration

For each [Relation.*] attribute on the entity class, the SG generates the corresponding Fluent API calls:

// [Relation.OneToMany<LineItem>] on Order — declared by the parent, so Cascade
builder.HasMany(e => e.LineItems)
    .WithOne(e => e.Order)
    .OnDelete(DeleteBehavior.Cascade);

// [Relation.ManyToOne<Customer>] on Order — declared by the child, so Restrict
builder.HasOne(e => e.Customer)
    .WithMany()
    .HasForeignKey(e => e.CustomerId)
    .IsRequired()
    .OnDelete(DeleteBehavior.Restrict);

// [Relation.OneToOne<RelationSide>] — the principal holds the FK
builder.HasOne(e => e.RelationSide)
    .WithOne()
    .HasForeignKey<Order>(e => e.RelationSideId)
    .OnDelete(DeleteBehavior.Restrict);

The navigation names come from the target type, pluralised for collections — LineItems, not any property you wrote. .WithNavigation("Items") on the relation renames it.

The delete behaviour depends on which side declares the relation: [Relation.OneToMany] on the parent gives Cascade, [Relation.ManyToOne] on the child gives Restrict, and an inverse the generator derives on its own gets NoAction. See Relationships — the default is not the cautious one.

Two Levels of Query Filters

The generated configuration includes two complementary filtering mechanisms:

1. EF Core Global Query Filter (in EntityConfiguration)

builder.HasQueryFilter("SoftDelete", e => !e.IsDeleted);

EF Core’s built-in mechanism, applied at the model level. It is a named filter, so it can be lifted on its own with IgnoreQueryFilters(["SoftDelete"]) rather than all-or-nothing.

2. Repository-Level Query Filter (IQueryFilter pipeline)

// In the generated repository
var filter = _filterProvider?.GetCombinedFilter<Order>(context);
query = query.Where(filter);

This is Pragmatic’s filter pipeline. It supports runtime toggle (IQueryFilterToggle), filter modes, and navigation-level filtering.

Why both? The EF Core filter provides a safety net — even if code bypasses the repository and queries the DbSet directly, soft-deleted records are still excluded. The Pragmatic filter pipeline adds runtime configurability (disable, modes, navigation filtering).

Inheritance Configuration

For entities with [Inheritance], a separate static configuration class is generated:

// ═══ Generated: {Namespace}.Fee.InheritanceMapping.g.cs ═══
public static class FeeInheritanceConfiguration
{
    public static void Configure(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Fee>()
            .HasDiscriminator<string>("FeeType")
            .HasValue<ServiceFee>("ServiceFee")
            .HasValue<CancellationFee>("CancellationFee");
    }
}

This is called in OnModelCreating after the ApplyConfiguration calls:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder);

    // Entity configurations
    modelBuilder.ApplyConfiguration(new FeeEntityConfiguration());
    modelBuilder.ApplyConfiguration(new ServiceFeeEntityConfiguration());

    // Inheritance mappings (after configurations)
    FeeInheritanceConfiguration.Configure(modelBuilder);
}

The order matters: entity configurations define properties and relationships, then inheritance configuration defines the discriminator and type mappings.