An audit record written by application code can miss changes made outside the application. Temporal tables move row-history capture into the database instead.

What Are Temporal Tables?

Temporal tables are a SQL Server feature that automatically maintains the full history of data changes. Every time a row is inserted, updated, or deleted, SQL Server copies the previous version to a history table with timestamps.

You don't need to write any audit logging code. The database handles it transparently. EF Core 6+ added first-class support for configuring and querying temporal tables.

Configuring Temporal Tables

Enable temporal tables in your entity configuration:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders", b => b.IsTemporal());
    }
}

That's it. When you create a migration, EF Core generates:

CREATE TABLE [Orders] (
    [Id] uniqueidentifier NOT NULL,
    [Status] nvarchar(50) NOT NULL,
    [TotalAmount] decimal(18,2) NOT NULL,
    [PeriodStart] datetime2 GENERATED ALWAYS AS ROW START NOT NULL,
    [PeriodEnd] datetime2 GENERATED ALWAYS AS ROW END NOT NULL,
    CONSTRAINT [PK_Orders] PRIMARY KEY ([Id]),
    PERIOD FOR SYSTEM_TIME ([PeriodStart], [PeriodEnd])
) WITH (SYSTEM_VERSIONING = ON (HISTORY_TABLE = [dbo].[OrdersHistory]));

SQL Server adds two hidden columns (PeriodStart and PeriodEnd) and creates a history table automatically.

Customizing Period Columns

You can customize the column names and history table name:

builder.ToTable("Orders", b => b.IsTemporal(t =>
{
    t.HasPeriodStart("ValidFrom");
    t.HasPeriodEnd("ValidTo");
    t.UseHistoryTable("OrderAuditHistory");
}));

The period columns are shadow properties. They don't exist on your entity class, but you can still read them in queries with EF.Property:

var orders = await context.Orders
    .Select(o => new
    {
        o.Id,
        o.Status,
        PeriodStart = EF.Property<DateTime>(o, "PeriodStart"),
        PeriodEnd = EF.Property<DateTime>(o, "PeriodEnd")
    })
    .ToListAsync();

Mapping the period columns to regular CLR properties on the entity isn't supported until EF Core 11 (in preview at the time of writing). On earlier versions, EF.Property is the only way to get at them.

How It Works

When you update an entity through EF Core:

var order = await context.Orders.FindAsync(orderId);
order.Status = OrderStatus.Shipped;
await context.SaveChangesAsync();

SQL Server automatically:

1. Copies the current row (with the old values) to the history table
2. Updates the current row with the new values
3. Sets the PeriodStart of the updated row to the transaction start time (UTC)
4. Sets the PeriodEnd of the history row to that same timestamp

You don't need to intercept SaveChangesAsync or use the change tracker for audit tracking. The database does everything.

Querying Current Data

Regular queries work exactly as before:

var orders = await context.Orders
    .Where(o => o.Status == OrderStatus.Shipped)
    .ToListAsync();

This returns only current data. The history table is invisible to normal queries.

TemporalAsOf

Query how the data looked at a specific point in time:

var yesterday = DateTime.UtcNow.AddDays(-1);

var ordersAsOfYesterday = await context.Orders
    .TemporalAsOf(yesterday)
    .Where(o => o.Id == orderId)
    .ToListAsync();

This returns the row as it existed at that exact timestamp. If an order was Confirmed yesterday but Shipped today, TemporalAsOf returns the Confirmed version.

TemporalBetween

Query all versions of a row within a time range:

var startDate = DateTime.UtcNow.AddDays(-7);
var endDate = DateTime.UtcNow;

var orderHistory = await context.Orders
    .TemporalBetween(startDate, endDate)
    .Where(o => o.Id == orderId)
    .OrderBy(o => EF.Property<DateTime>(o, "PeriodStart"))
    .ToListAsync();

This returns every version of the order from the last seven days. You get one row for each change.

TemporalAll

Get the complete history of a row from creation to now:

var fullHistory = await context.Orders
    .TemporalAll()
    .Where(o => o.Id == orderId)
    .OrderBy(o => EF.Property<DateTime>(o, "PeriodStart"))
    .Select(o => new
    {
        o.Id,
        o.Status,
        o.TotalAmount,
        ValidFrom = EF.Property<DateTime>(o, "PeriodStart"),
        ValidTo = EF.Property<DateTime>(o, "PeriodEnd")
    })
    .ToListAsync();

This includes the current row and all historical versions. It's useful for building audit trails and change history views.

TemporalContainedIn and TemporalFromTo

Two more temporal operators for specific range semantics:

// Rows whose validity period started AND ended within the range
var contained = await context.Orders
    .TemporalContainedIn(startDate, endDate)
    .Where(o => o.Id == orderId)
    .ToListAsync();

// Rows that were active at any point between the two times
var fromTo = await context.Orders
    .TemporalFromTo(startDate, endDate)
    .Where(o => o.Id == orderId)
    .ToListAsync();

TemporalBetween is nearly identical to TemporalFromTo. The difference: it also includes rows that became active exactly on the upper boundary.

Restoring Deleted Data

One powerful use case - restoring accidentally deleted records:

// Find the deleted order in history
var deletedOrder = await context.Orders
    .TemporalAll()
    .Where(o => o.Id == orderId)
    .OrderByDescending(o => EF.Property<DateTime>(o, "PeriodStart"))
    .FirstOrDefaultAsync();

if (deletedOrder is not null)
{
    // Re-insert it
    context.Orders.Add(new Order
    {
        Id = deletedOrder.Id,
        Status = deletedOrder.Status,
        TotalAmount = deletedOrder.TotalAmount
    });

    await context.SaveChangesAsync();
}

The history table preserves deleted row versions until its retention or cleanup policy removes them, giving you a recovery path inside that window.

Queries using temporal operators are no-tracking by default. A historical version is not the current row, so EF Core keeps it out of the change tracker, and loading history while the current version is tracked doesn't cause identity conflicts. That's also why the restore example creates a new Order instead of re-attaching the historical instance.

Managing History Growth

Every update writes a row to the history table. On a hot table, that adds up fast, and the history table has no automatic cleanup by default.

SQL Server has a built-in retention policy, but EF Core doesn't expose it. Apply it with raw SQL in a migration:

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.Sql(
        @"ALTER TABLE [Orders]
          SET (SYSTEM_VERSIONING = ON (HISTORY_RETENTION_PERIOD = 6 MONTHS));");
}

SQL Server then deletes history rows older than six months in the background. Pick a retention period that matches your compliance requirements. Keeping history forever on a frequently updated table just grows your storage bill.

Temporal Tables vs Application-Level Auditing

Temporal tables answer what changed and when. They can't answer who changed it or why, because SQL Server never sees your user context.

Use temporal tables when:

• You need point-in-time reconstruction of data (regulatory snapshots, debugging "what did the customer see")
• You want zero application code for history tracking
• You're on SQL Server and can afford the storage

Use application-level audit logging when:

• You need the acting user, correlation ID, or business reason attached to each change
• You're on PostgreSQL or another provider
• You only care about a handful of important entities, not every column change

In practice, many systems combine both: temporal tables for full data history, plus a lightweight audit log with user context via EF Core interceptors.

Limitations

Temporal tables have a few constraints:

• SQL Server only - PostgreSQL and other databases have different history mechanisms
• No filtering on history table - you can't add query filters to the history table
• Storage growth - frequent updates on large tables generate significant history data
• Schema changes - altering temporal tables requires extra care in migrations

Summary

SQL Server temporal tables preserve row versions independently of the application write path. Use EF Core's temporal operators for point-in-time reads and recovery, then define retention and storage policies before history grows without bound. Add a separate application audit trail when you also need to know who made a change and why.

The rest of the configuration that matters is where entity configuration lives, the default tracking behavior, connection retries, interceptors, and whether pooling is worth its constraints. A good setup keeps requests isolated, startup predictable, and database concerns out of application code.

What Is DbContext?

DbContext is your session with the database. It tracks changes to your entities, generates SQL, and manages the connection and transactions.

Every EF Core operation goes through the DbContext. How you configure and use it directly impacts the performance and correctness of your application.

Registration and Lifetime

Register your DbContext with the DI container using AddDbContext:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Database")));

The default lifetime is Scoped - one instance per HTTP request. This is correct for most web applications.

Never register DbContext as Singleton. It's not thread-safe, and you'll get concurrency exceptions.

For background services, create a scope manually:

public class OrderProcessingService(IServiceScopeFactory scopeFactory)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var scope = scopeFactory.CreateScope();
        var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        // Use dbContext within this scope
    }
}

For more on DI lifetimes, see Dependency Injection Lifetimes in .NET.

Applying Entity Configurations

Don't configure entities inline in OnModelCreating. Use IEntityTypeConfiguration<T> classes:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.HasKey(o => o.Id);

        builder.Property(o => o.Status)
            .HasConversion<string>()
            .HasMaxLength(50);

        builder.HasMany(o => o.LineItems)
            .WithOne()
            .HasForeignKey(li => li.OrderId)
            .OnDelete(DeleteBehavior.Cascade);

        builder.ComplexProperty(o => o.TotalAmount, money =>
        {
            money.Property(m => m.Amount).HasColumnName("total_amount");
            money.Property(m => m.Currency).HasColumnName("total_currency");
        });
    }
}

Apply all configurations automatically:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
}

This keeps your DbContext class clean and each entity's configuration in its own file.

Connection Resiliency

Network issues happen. Configure retry logic for transient failures:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(
        builder.Configuration.GetConnectionString("Database"),
        npgsqlOptions => npgsqlOptions
            .EnableRetryOnFailure(
                maxRetryCount: 3,
                maxRetryDelay: TimeSpan.FromSeconds(5),
                errorCodesToAdd: null)));

This handles temporary database outages without crashing your application. I cover the details (including the execution strategy gotchas with manual transactions) in EF Core connection resiliency.

Query Tracking Behavior

By default, EF Core tracks all entities returned by queries. This is useful for write operations but wasteful for read-only queries.

Option 1: Disable tracking globally, enable per query:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString)
          .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));

Then opt in when you need tracking:

var order = await _dbContext.Orders
    .AsTracking()
    .FirstOrDefaultAsync(o => o.Id == orderId);

Option 2: Keep tracking on, use AsNoTracking for reads:

var orders = await _dbContext.Orders
    .AsNoTracking()
    .Where(o => o.Status == OrderStatus.Pending)
    .ToListAsync();

If you're using CQRS, query handlers should always use AsNoTracking() since they never modify data.

Interceptors

EF Core Interceptors let you hook into the database pipeline for cross-cutting concerns:

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
    options.UseNpgsql(connectionString)
           .AddInterceptors(
               sp.GetRequiredService<PublishDomainEventsInterceptor>(),
               sp.GetRequiredService<AuditableEntityInterceptor>()));

builder.Services.AddScoped<PublishDomainEventsInterceptor>();
builder.Services.AddScoped<AuditableEntityInterceptor>();

Common interceptor use cases:

• Publishing domain events after SaveChanges
• Setting CreatedAt and ModifiedAt timestamps automatically
• Audit logging and soft-delete behavior
• Query logging and diagnostics

Split Read/Write Contexts

For applications with different read and write patterns, consider separate DbContext classes:

// Write context - full entity model with change tracking
public class WriteDbContext : DbContext
{
    public WriteDbContext(DbContextOptions<WriteDbContext> options) : base(options) { }

    public DbSet<Order> Orders { get; set; }
    public DbSet<Customer> Customers { get; set; }
}

// Read context - optimized for queries
public class ReadDbContext : DbContext
{
    public ReadDbContext(DbContextOptions<ReadDbContext> options) : base(options) { }

    // Read models, not domain entities
    public DbSet<OrderReadModel> Orders { get; set; }
}

Register them with different configurations:

builder.Services.AddDbContext<WriteDbContext>(options =>
    options.UseNpgsql(writeConnectionString));

builder.Services.AddDbContext<ReadDbContext>(options =>
    options.UseNpgsql(readConnectionString)
           .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));

This is particularly useful with read replicas. When the contexts point to genuinely separate stores rather than replicas, keep their models and migrations isolated as described in using multiple databases with EF Core.

Pooling

For high-throughput applications, use AddDbContextPool to reuse DbContext instances:

builder.Services.AddDbContextPool<AppDbContext>(options =>
    options.UseNpgsql(connectionString),
    poolSize: 128);

Pooling avoids the overhead of creating a new DbContext for every request. The default pool size is 1024.

Note: Pooled contexts come with constraints. The context is reset and reused, so it can only have a single public constructor accepting DbContextOptions - you can't inject other services into it, and you shouldn't store any private state on the context. If your DbContext injects a tenant provider or current-user service, pooling isn't for you.

To be clear about the benefit: pooling saves the allocation and setup cost of the context instance itself. It's measurable in benchmarks, but for most business applications the difference is negligible. Don't reach for it until profiling says so.

If you need to create contexts on demand (Blazor components, parallel operations, background jobs), use a context factory:

builder.Services.AddPooledDbContextFactory<AppDbContext>(options =>
    options.UseNpgsql(connectionString));

public class ReportGenerator(IDbContextFactory<AppDbContext> factory)
{
    public async Task GenerateAsync()
    {
        await using var dbContext = await factory.CreateDbContextAsync();
        // Each call gets its own context instance
    }
}

Unit of Work Pattern

DbContext already implements the Unit of Work pattern - SaveChangesAsync commits all tracked changes in a single transaction.

Expose it through an interface for Clean Architecture:

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

public class AppDbContext : DbContext, IUnitOfWork
{
    // SaveChangesAsync is already implemented by DbContext
}

Your Application layer depends on IUnitOfWork (abstraction), not on AppDbContext (implementation).

For more details, see Unit of Work Pattern With EF Core.

Common Mistakes

1. Injecting DbContext into singleton services - causes thread-safety issues. Use IDbContextFactory or IServiceScopeFactory instead.

2. Not disposing DbContext - handled automatically by DI when registered as Scoped, but be careful with manual creation.

3. Loading too much data - always filter and project. Use Select to return only the columns you need.

4. Ignoring the N+1 problem - use Include for related data or project with Select. See N+1 Query Problem in EF Core.

5. Not using transactions explicitly for multi-step operations - SaveChangesAsync is transactional, but if you call it multiple times, each call is a separate transaction. Wrap multi-save operations in an explicit transaction:

await using var transaction =
    await _dbContext.Database.BeginTransactionAsync();

_dbContext.Orders.Add(order);
await _dbContext.SaveChangesAsync();

_dbContext.Shipments.Add(shipment);
await _dbContext.SaveChangesAsync();

await transaction.CommitAsync();

6. Sharing a DbContext across threads - the context is not thread-safe. Never run parallel queries on the same instance; create a context per parallel operation with IDbContextFactory.

Summary

Treat a DbContext as one short-lived unit of work and never share it across concurrent operations. Keep entity configuration external, match tracking to query intent, and use interceptors for persistence concerns that truly apply to every write. Pooling and retry policies are workload-specific optimizations, not substitutes for a clear context boundary.

An update tells you what the database looks like now. It does not tell you who changed it, what the previous value was, or which request made the change. EF Core interceptors can capture that history at the persistence boundary without spreading audit code through every use case.

Why Audit Logging?

Audit logging answers the question "who changed this and when?" Regulatory compliance often requires it, and it makes debugging production data issues far easier.

The challenge is implementing it without scattering audit code across every handler. If every command handler has to remember to write an audit record, someone will forget, and you'll discover the gap during an incident review.

EF Core interceptors give us a single place to capture changes. Every write goes through SaveChanges, so an interceptor sees everything.

The Audit Log Entity

public class AuditLogEntry
{
    public Guid Id { get; set; }
    public string EntityName { get; set; }
    public string EntityId { get; set; }
    public string Action { get; set; } // Added, Modified, Deleted
    public string? UserId { get; set; }
    public DateTime Timestamp { get; set; }
    public string? OldValues { get; set; }
    public string? NewValues { get; set; }
    public string? AffectedColumns { get; set; }
}

The IAuditable Marker Interface

Tag entities you want to audit:

public interface IAuditable { }

public class Order : IAuditable
{
    public Guid Id { get; set; }
    public OrderStatus Status { get; set; }
    public decimal TotalAmount { get; set; }
    public string CustomerId { get; set; }
}

The SaveChanges Interceptor

public sealed class AuditLoggingInterceptor : SaveChangesInterceptor
{
    private readonly ICurrentUserService _currentUser;

    public AuditLoggingInterceptor(ICurrentUserService currentUser)
    {
        _currentUser = currentUser;
    }

    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken ct = default)
    {
        var context = eventData.Context;

        if (context is null)
        {
            return base.SavingChangesAsync(eventData, result, ct);
        }

        var auditEntries = CreateAuditEntries(context);

        context.Set<AuditLogEntry>().AddRange(auditEntries);

        return base.SavingChangesAsync(eventData, result, ct);
    }

    private List<AuditLogEntry> CreateAuditEntries(DbContext context)
    {
        var entries = new List<AuditLogEntry>();

        context.ChangeTracker.DetectChanges();

        foreach (var entry in context.ChangeTracker.Entries<IAuditable>())
        {
            if (entry.State is EntityState.Detached or EntityState.Unchanged)
            {
                continue;
            }

            var auditEntry = new AuditLogEntry
            {
                Id = Guid.NewGuid(),
                EntityName = entry.Entity.GetType().Name,
                EntityId = GetPrimaryKey(entry),
                UserId = _currentUser.UserId,
                Timestamp = DateTime.UtcNow,
                Action = entry.State.ToString()
            };

            switch (entry.State)
            {
                case EntityState.Added:
                    auditEntry.NewValues = SerializeProperties(
                        entry.Properties);
                    break;

                case EntityState.Modified:
                    auditEntry.OldValues = SerializeOldValues(entry);
                    auditEntry.NewValues = SerializeNewValues(entry);
                    auditEntry.AffectedColumns = GetModifiedColumns(entry);
                    break;

                case EntityState.Deleted:
                    auditEntry.OldValues = SerializeProperties(
                        entry.Properties);
                    break;
            }

            entries.Add(auditEntry);
        }

        return entries;
    }
}

ICurrentUserService is a small abstraction that exposes the authenticated user's id from the current request.

This overrides only the async path. If any code path calls the synchronous SaveChanges, override SavingChanges as well and reuse the same CreateAuditEntries logic.

Helper Methods

private static string GetPrimaryKey(EntityEntry entry)
{
    // Handles composite keys by joining all key parts
    var keyParts = entry.Properties
        .Where(p => p.Metadata.IsPrimaryKey())
        .Select(p => p.CurrentValue?.ToString() ?? "null");

    return string.Join(",", keyParts);
}

private static string SerializeProperties(
    IEnumerable<PropertyEntry> properties)
{
    var dict = properties.ToDictionary(
        p => p.Metadata.Name,
        p => p.CurrentValue);

    return JsonSerializer.Serialize(dict);
}

private static string SerializeOldValues(EntityEntry entry)
{
    var dict = entry.Properties
        .Where(p => p.IsModified)
        .ToDictionary(
            p => p.Metadata.Name,
            p => p.OriginalValue);

    return JsonSerializer.Serialize(dict);
}

private static string SerializeNewValues(EntityEntry entry)
{
    var dict = entry.Properties
        .Where(p => p.IsModified)
        .ToDictionary(
            p => p.Metadata.Name,
            p => p.CurrentValue);

    return JsonSerializer.Serialize(dict);
}

private static string GetModifiedColumns(EntityEntry entry)
{
    var columns = entry.Properties
        .Where(p => p.IsModified)
        .Select(p => p.Metadata.Name);

    return string.Join(",", columns);
}

Registration

builder.Services.AddDbContext<ApplicationDbContext>((sp, options) =>
{
    options.UseNpgsql(connectionString);
    options.AddInterceptors(
        sp.GetRequiredService<AuditLoggingInterceptor>());
});

builder.Services.AddScoped<AuditLoggingInterceptor>();

The DbContext Configuration

public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }

    public DbSet<AuditLogEntry> AuditLogs { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<AuditLogEntry>(builder =>
        {
            builder.ToTable("AuditLogs");
            builder.HasKey(x => x.Id);
            builder.HasIndex(x => x.EntityName);
            builder.HasIndex(x => x.Timestamp);
            builder.HasIndex(x => new { x.EntityName, x.EntityId });
        });
    }
}

Querying the Audit Log

public sealed class GetAuditHistoryHandler
    : IRequestHandler<GetAuditHistoryQuery, List<AuditLogEntry>>
{
    private readonly ApplicationDbContext _db;

    public GetAuditHistoryHandler(ApplicationDbContext db)
    {
        _db = db;
    }

    public async Task<List<AuditLogEntry>> Handle(
        GetAuditHistoryQuery query, CancellationToken ct)
    {
        return await _db.AuditLogs
            .Where(a => a.EntityName == query.EntityName &&
                        a.EntityId == query.EntityId)
            .OrderByDescending(a => a.Timestamp)
            .ToListAsync(ct);
    }
}

Don't Log Sensitive Data

The audit log serializes every property by default. That includes password hashes, API keys, and personal data.

Audit tables are a classic PII blind spot: teams carefully encrypt the Users table, then store every historical value of it in plain JSON next door. If you're subject to GDPR, "delete this user's data" now includes the audit log too.

The fix is a deny list (or an attribute) applied before serialization:

private static readonly HashSet<string> ExcludedProperties =
    ["PasswordHash", "SecurityStamp", "RefreshToken"];

private static string SerializeProperties(
    IEnumerable<PropertyEntry> properties)
{
    var dict = properties
        .Where(p => !ExcludedProperties.Contains(p.Metadata.Name))
        .ToDictionary(
            p => p.Metadata.Name,
            p => p.CurrentValue);

    return JsonSerializer.Serialize(dict);
}

Decide what's excluded when you build the feature, not after your first data audit.

Performance and Retention

Practical production considerations:

• Every audited change is an extra insert. For typical CRUD workloads, this is noise. For hot write paths (thousands of writes per second), audit selectively - that's exactly what the IAuditable marker is for.
• The audit table grows forever unless you do something about it. Add a retention job that archives or deletes entries older than your compliance window.
• Index intentionally. The indexes in the DbContext configuration above support "history of this entity" queries. Skip indexes you don't query on; they slow down every insert.
• Don't query audit JSON in hot paths. If you need to report on audit data, project it into a proper reporting table instead of parsing JSON columns at query time.

Soft Deletes + Audit Log

Combine audit logging with soft deletes:

public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
    DbContextEventData eventData,
    InterceptionResult<int> result,
    CancellationToken ct = default)
{
    var context = eventData.Context;

    if (context is null)
    {
        return base.SavingChangesAsync(eventData, result, ct);
    }

    // Handle soft deletes
    foreach (var entry in context.ChangeTracker
        .Entries<ISoftDeletable>()
        .Where(e => e.State == EntityState.Deleted))
    {
        entry.State = EntityState.Modified;
        entry.Entity.IsDeleted = true;
        entry.Entity.DeletedAt = DateTime.UtcNow;
    }

    // Create audit entries (includes soft delete as "Modified")
    var auditEntries = CreateAuditEntries(context);
    context.Set<AuditLogEntry>().AddRange(auditEntries);

    return base.SavingChangesAsync(eventData, result, ct);
}

Alternative: Temporal Tables

SQL Server temporal tables provide database-level change tracking. They're a great fit when you need point-in-time queries ("what did this row look like last Tuesday?") with zero application code.

But they only track what changed, not who changed it, and they capture the full row rather than just the modified columns. They also don't see changes as business actions - just row versions.

For user-level audit trails, use the interceptor approach. For time-travel queries or protection against direct SQL modifications, use temporal tables. Some systems justify both.

One more caveat for the interceptor approach: it only sees changes that go through the change tracker. Bulk operations like ExecuteUpdateAsync and raw SQL bypass SaveChanges entirely, so they bypass your audit log too. If you use bulk updates, write their audit entries explicitly.

Summary

SaveChangesInterceptor is a useful audit boundary because it sees tracked inserts, updates, and deletes in one place. Filter the audited entities and properties, include user context, and keep sensitive values out of the payload. Bulk APIs and raw SQL bypass this path, so cover those writes separately or make the limitation explicit.

DbContext Is Already a Unit of Work

The Unit of Work pattern groups all the changes made during one business operation and commits them together in a single transaction.

Before implementing anything, let's acknowledge the obvious: DbContext is a Unit of Work. It does exactly that when you call SaveChangesAsync.

The change tracker collects every insert, update, and delete. SaveChangesAsync wraps them all in a transaction. Either everything succeeds or nothing does. That's the Unit of Work pattern.

So why would you create an explicit IUnitOfWork interface?

Why an Explicit Abstraction?

There are two practical reasons:

1. Dependency inversion - your domain and application layers shouldn't reference DbContext or EF Core directly. An IUnitOfWork interface lets them coordinate persistence without knowing the implementation.

2. Controlled save points - when multiple repositories modify entities in the same business operation, you want a single SaveChangesAsync call at the end. An explicit Unit of Work makes this coordination visible.

If your application layer already references EF Core and you're fine with that coupling, you might not need a separate abstraction. But in clean architecture or projects following DDD, the abstraction pays for itself.

Defining the Interface

Keep it minimal:

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

That's the core contract. The application layer calls SaveChangesAsync when the business operation is complete. It doesn't know or care that EF Core is behind it.

Implementing With DbContext

The implementation is straightforward - your DbContext implements IUnitOfWork:

public class AppDbContext : DbContext, IUnitOfWork
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options)
    {
    }

    public DbSet<Order> Orders { get; set; }
    public DbSet<Customer> Customers { get; set; }
    public DbSet<Product> Products { get; set; }
}

DbContext already has SaveChangesAsync, so it satisfies the interface without any additional code.

Register both:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString));

builder.Services.AddScoped<IUnitOfWork>(sp =>
    sp.GetRequiredService<AppDbContext>());

Both AppDbContext and IUnitOfWork resolve to the same instance within a scope. This is critical - repositories and the Unit of Work must share the same DbContext.

Coordinating Repositories

Here's the pattern in a use case. Multiple repositories make changes, and a single SaveChangesAsync commits everything:

public class PlaceOrderCommandHandler
{
    private readonly IOrderRepository _orderRepository;
    private readonly ICustomerRepository _customerRepository;
    private readonly IUnitOfWork _unitOfWork;

    public PlaceOrderCommandHandler(
        IOrderRepository orderRepository,
        ICustomerRepository customerRepository,
        IUnitOfWork unitOfWork)
    {
        _orderRepository = orderRepository;
        _customerRepository = customerRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task Handle(PlaceOrderCommand command, CancellationToken ct)
    {
        var customer = await _customerRepository.GetByIdAsync(command.CustomerId, ct);

        var order = Order.Create(customer.Id, command.Items);

        customer.IncrementOrderCount();

        _orderRepository.Add(order);

        await _unitOfWork.SaveChangesAsync(ct);
    }
}

Both the Order insert and the Customer update happen in one transaction. If either fails, both are rolled back.

Repository Pattern With Unit of Work

The repositories handle querying and adding entities. They don't call SaveChangesAsync:

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default);
    void Add(Order order);
    void Remove(Order order);
}

public class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public OrderRepository(AppDbContext context)
    {
        _context = context;
    }

    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)
    {
        return await _context.Orders
            .Include(o => o.LineItems)
            .FirstOrDefaultAsync(o => o.Id == id, ct);
    }

    public void Add(Order order)
    {
        _context.Orders.Add(order);
    }

    public void Remove(Order order)
    {
        _context.Orders.Remove(order);
    }
}

Notice that Add and Remove are synchronous. They only tell the change tracker about the entity. The actual database operation happens in SaveChangesAsync.

Explicit Transactions

Sometimes SaveChangesAsync isn't enough. You need multiple save points or you're coordinating with external systems. Use explicit transactions:

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
    Task BeginTransactionAsync(CancellationToken cancellationToken = default);
    Task CommitTransactionAsync(CancellationToken cancellationToken = default);
    Task RollbackTransactionAsync(CancellationToken cancellationToken = default);
}

Implementation:

public class AppDbContext : DbContext, IUnitOfWork
{
    private IDbContextTransaction? _transaction;

    public async Task BeginTransactionAsync(CancellationToken ct)
    {
        _transaction = await Database.BeginTransactionAsync(ct);
    }

    public async Task CommitTransactionAsync(CancellationToken ct)
    {
        if (_transaction is null) return;

        await _transaction.CommitAsync(ct);
        await _transaction.DisposeAsync();
        _transaction = null;
    }

    public async Task RollbackTransactionAsync(CancellationToken ct)
    {
        if (_transaction is null) return;

        await _transaction.RollbackAsync(ct);
        await _transaction.DisposeAsync();
        _transaction = null;
    }
}

Use it when a business operation has multiple steps that each need to be persisted:

await _unitOfWork.BeginTransactionAsync(ct);

try
{
    _orderRepository.Add(order);
    await _unitOfWork.SaveChangesAsync(ct);

    await _paymentService.ChargeAsync(order.TotalAmount, ct);

    order.MarkAsPaid();
    await _unitOfWork.SaveChangesAsync(ct);

    await _unitOfWork.CommitTransactionAsync(ct);
}
catch
{
    await _unitOfWork.RollbackTransactionAsync(ct);
    throw;
}

A word of caution about that example: holding a database transaction open across an external HTTP call (the payment charge) means a slow payment provider keeps your database connection and locks tied up. It's acceptable for low-traffic flows, but at scale you want the Outbox pattern instead: commit locally, then integrate asynchronously.

One more gotcha: if you enabled a retrying execution strategy (EnableRetryOnFailure), you can't just call BeginTransactionAsync. Wrap the whole operation in CreateExecutionStrategy().ExecuteAsync(...), or EF Core throws because a retry can't replay a manually started transaction.

Domain Events and Unit of Work

If you're using domain events, dispatch them after SaveChangesAsync succeeds. This ensures events aren't published for changes that were rolled back:

public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
{
    var domainEvents = ChangeTracker.Entries<Entity>()
        .SelectMany(e => e.Entity.PopDomainEvents())
        .ToList();

    var result = await base.SaveChangesAsync(ct);

    foreach (var domainEvent in domainEvents)
    {
        await _publisher.Publish(domainEvent, ct);
    }

    return result;
}

The _publisher field is whatever event dispatcher you inject into the context (MediatR's IPublisher, for example).

Note the tradeoff: publishing after the save means a crash between the save and the publish loses the events. If the events must not be lost, persist them in the same transaction using the transactional outbox instead of publishing in memory.

When You Don't Need IUnitOfWork

Not every project needs this abstraction. Skip it when:

• Your application layer already depends on EF Core
• You have simple CRUD operations with a single repository per use case
• You're building a small API without layered architecture

In these cases, inject AppDbContext directly and call SaveChangesAsync in your handler. Adding IUnitOfWork would be ceremony without value.

Summary

DbContext already tracks changes and commits them as a unit. Add IUnitOfWork only when the application needs a narrow commit boundary, and ensure every participating repository shares the same scoped context. Use an explicit transaction for multiple saves that must roll back together, not as ceremony around a single SaveChanges call.

What Is the Repository Pattern?

The Repository pattern mediates between the domain and data mapping layers. It provides a collection-like interface for accessing domain objects, hiding the details of how data is persisted or retrieved.

In simpler terms: instead of your business logic talking directly to the database, it talks to a repository. The repository handles the data access behind the scenes.

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(int id, CancellationToken cancellationToken = default);
    Task<List<Order>> GetByCustomerAsync(int customerId, CancellationToken cancellationToken = default);
    void Add(Order order);
    void Remove(Order order);
}

The caller doesn't know (or care) whether you're using EF Core, Dapper, or a flat file. That's the whole point.

Why Use the Repository Pattern?

There are a few practical reasons to add repositories on top of EF Core:

1. Abstraction over data access - Your domain and application layers don't depend on DbContext. If you're following Clean Architecture, this keeps the Dependency Rule intact.

2. Testability - You can mock IOrderRepository in unit tests without setting up a database. Testing use cases in Clean Architecture becomes straightforward. For the repository implementations themselves, use real databases in integration tests.

3. Encapsulation of query logic - Complex queries live inside the repository, not scattered across your application. This makes them easier to find, optimize, and reuse.

4. Consistent data access patterns - Repositories give your team a clear pattern to follow. Every developer knows where data access code lives.

Implementing a Repository With EF Core

Here's a concrete implementation of the IOrderRepository:

public class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _dbContext;

    public OrderRepository(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<Order?> GetByIdAsync(
        int id,
        CancellationToken cancellationToken = default)
    {
        return await _dbContext.Orders
            .Include(o => o.LineItems)
            .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);
    }

    public async Task<List<Order>> GetByCustomerAsync(
        int customerId,
        CancellationToken cancellationToken = default)
    {
        return await _dbContext.Orders
            .Where(o => o.CustomerId == customerId)
            .OrderByDescending(o => o.CreatedAt)
            .ToListAsync(cancellationToken);
    }

    public void Add(Order order)
    {
        _dbContext.Orders.Add(order);
    }

    public void Remove(Order order)
    {
        _dbContext.Orders.Remove(order);
    }
}

Notice that Add and Remove don't call SaveChanges. That's intentional - saving is the responsibility of the Unit of Work, not the repository.

The Unit of Work Pattern

Repositories handle individual aggregate persistence. The Unit of Work coordinates saving changes across multiple repositories in a single transaction.

EF Core's DbContext already implements the Unit of Work pattern internally. But exposing a clean interface keeps your code decoupled (I cover the full pattern in Unit of Work with EF Core):

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

public class UnitOfWork : IUnitOfWork
{
    private readonly AppDbContext _dbContext;

    public UnitOfWork(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
    {
        return await _dbContext.SaveChangesAsync(cancellationToken);
    }
}

Now your use case can orchestrate multiple repositories and save once:

public async Task Handle(PlaceOrderCommand command, CancellationToken cancellationToken)
{
    var customer = await _customerRepository.GetByIdAsync(command.CustomerId, cancellationToken);

    var order = Order.Create(customer, command.Items);

    _orderRepository.Add(order);

    customer.IncrementOrderCount();

    await _unitOfWork.SaveChangesAsync(cancellationToken);
}

The Generic Repository Debate

You'll find many tutorials suggesting a generic repository:

public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync(int id);
    Task<List<T>> GetAllAsync();
    void Add(T entity);
    void Update(T entity);
    void Remove(T entity);
}

I'd advise against this approach for most projects. Here's why:

It's a leaky abstraction. You end up exposing methods that don't make sense for every entity. Should you really be able to call GetAll() on a table with millions of rows?

It pushes query logic into the wrong place. Callers end up writing LINQ against IQueryable<T>, which defeats the purpose of the repository.

It mirrors DbSet. If your generic repository just wraps DbSet<T>, you haven't gained anything meaningful - you've just added a layer of indirection.

Better alternative: Write specific repository interfaces per aggregate root. Each interface exposes only the operations that make sense for that aggregate.

// ✅ Specific repository - clear intent
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(int id);
    Task<List<Order>> GetPendingOrdersAsync();
    void Add(Order order);
}

// ❌ Generic repository - unclear intent
public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync(int id);
    Task<List<T>> GetAllAsync(); // Millions of rows?
    void Add(T entity);
    void Update(T entity); // EF Core tracks changes automatically
    void Remove(T entity);
}

Should Repositories Return IQueryable?

A common shortcut is exposing IQueryable<T> from the repository:

// ❌ Avoid this
public interface IOrderRepository
{
    IQueryable<Order> Orders { get; }
}

It looks flexible, but it defeats the purpose of the pattern:

The abstraction leaks. Callers can compose any query, including ones that don't translate to SQL. The exception surfaces far from the code that caused it, at enumeration time.

Query logic scatters. The whole point was to centralize data access. With IQueryable, every handler writes its own Include, filtering, and paging logic.

You can't test the contract. An in-memory IQueryable behaves differently from the EF Core provider (case sensitivity, null handling, unsupported translations). Your mocks pass while production fails.

Return materialized results (List<T>, T?) or accept a specification object instead. If a handler needs a truly one-off query, that's a sign it should use DbContext directly - and that's fine.

When to Skip the Repository Pattern

The repository pattern isn't always necessary. Skip it when:

You're building a simple CRUD app. If your app mostly does basic create-read-update-delete operations, the repository adds overhead without meaningful benefit. Just use DbContext directly.

You're using Vertical Slice Architecture. In VSA, each slice owns its data access. Adding a repository per slice is over-engineering - your handler is the data access boundary.

You'll never swap your ORM. The "what if we switch from EF Core to Dapper" argument rarely materializes. If you're committed to EF Core, the abstraction may not justify its cost.

Your team is small and co-located. Conventions and code reviews can enforce consistency without a formal pattern.

Repository Pattern in Clean Architecture

In Clean Architecture, repository interfaces live in the Domain layer (or Application layer) and implementations live in the Infrastructure layer.

Domain/
  Entities/
    Order.cs
  Repositories/
    IOrderRepository.cs      ← Interface here

Infrastructure/
  Repositories/
    OrderRepository.cs        ← Implementation here

This keeps your domain free of EF Core dependencies while still allowing rich data access behind the scenes.

Register the repository in your DI container:

builder.Services.AddScoped<IOrderRepository, OrderRepository>();
builder.Services.AddScoped<IUnitOfWork, UnitOfWork>();

Or use Scrutor for automatic registration by convention.

Repository Pattern With the Specification Pattern

For complex query scenarios, combine repositories with the Specification pattern. Specifications encapsulate query criteria into reusable objects:

public class PendingOrdersSpecification : Specification<Order>
{
    public override Expression<Func<Order, bool>> ToExpression()
    {
        return order => order.Status == OrderStatus.Pending
                     && order.CreatedAt >= DateTime.UtcNow.AddDays(-30);
    }
}

The abstract Specification<T> base class only needs to declare the ToExpression method. The repository applies the specification to the query:

public async Task<List<Order>> GetAsync(
    Specification<Order> specification,
    CancellationToken cancellationToken = default)
{
    return await _dbContext.Orders
        .Where(specification.ToExpression())
        .ToListAsync(cancellationToken);
}

This avoids query logic leaking out of the repository while keeping things flexible.

Summary

The repository pattern is a useful abstraction when:

• You're following Clean Architecture and need to enforce the Dependency Rule
• You want to isolate query logic in a consistent, testable way
• Your domain has complex data access requirements beyond simple CRUD

Skip it when:

• You're building simple CRUD applications
• You're using Vertical Slice Architecture where each handler owns its data access
• The abstraction adds complexity without meaningful benefit

Avoid generic CRUD repositories. When a repository protects a real aggregate boundary, expose only the operations and query intent that boundary needs. EF Core already supplies a unit of work and identity map, so the repository should organize domain-facing access rather than recreate the ORM.

Optimistic concurrency detects a race after another writer wins. Some workflows need to prevent the conflicting work from starting, or let several workers claim different rows without waiting on each other. PostgreSQL row and advisory locks provide those guarantees, but only while their transaction and timeout rules are explicit.

When You Need Database Locks

Optimistic concurrency works great when conflicts are rare. But in high-contention scenarios - ticket booking, inventory management, financial transfers - retrying failed operations can be expensive or impractical.

That's when you lock rows in the database: acquire the lock first, then make your changes. No other transaction can modify the locked row until you commit or roll back.

I covered the general EF Core approach in pessimistic locking in EF Core. This article goes deeper into what PostgreSQL specifically gives you: FOR UPDATE and its variants, SKIP LOCKED job queues, and advisory locks.

SELECT FOR UPDATE From EF Core

PostgreSQL's SELECT FOR UPDATE acquires a row-level lock on every row returned by the query. Other transactions that try to lock the same rows will block until the lock is released.

EF Core doesn't have built-in support for SELECT FOR UPDATE, but you can use raw SQL:

public async Task<Order?> GetOrderForUpdate(
    AppDbContext context,
    Guid orderId,
    CancellationToken ct = default)
{
    return await context.Orders
        .FromSqlInterpolated(
            $@"SELECT * FROM ""Orders""
               WHERE ""Id"" = {orderId}
               FOR UPDATE")
        .FirstOrDefaultAsync(ct);
}

The entity comes back fully tracked, so the normal SaveChangesAsync workflow still applies. The lock is held for the duration of the transaction and released when it commits or rolls back.

The Full Transaction Pattern

The lock only makes sense inside an explicit transaction. Without one, PostgreSQL runs the statement in its own auto-committed transaction, and the lock is released the moment the query finishes.

public async Task ProcessPayment(Guid orderId, decimal amount)
{
    await using var transaction = await context.Database
        .BeginTransactionAsync();

    try
    {
        // Lock the row - other transactions will wait here
        var order = await context.Orders
            .FromSqlInterpolated(
                $@"SELECT * FROM ""Orders""
                   WHERE ""Id"" = {orderId}
                   FOR UPDATE")
            .FirstOrDefaultAsync();

        if (order is null)
        {
            throw new InvalidOperationException("Order not found.");
        }

        order.RecordPayment(amount);

        await context.SaveChangesAsync();
        await transaction.CommitAsync();
    }
    catch
    {
        await transaction.RollbackAsync();
        throw;
    }
}

Between BeginTransactionAsync and CommitAsync, the locked row is exclusively yours. Any other transaction running the same SELECT FOR UPDATE will block until this transaction completes.

One caveat if you enabled EnableRetryOnFailure: a retrying execution strategy can't replay a manually started transaction, so EF Core throws when you call BeginTransactionAsync. Wrap the whole operation in CreateExecutionStrategy().ExecuteAsync(...) in that case.

PostgreSQL Row Lock Modes

FOR UPDATE is the strongest row lock, but PostgreSQL has a whole family of locking clauses:

-- Blocks other FOR UPDATE, allows plain reads
SELECT * FROM "Orders" WHERE "Id" = @id FOR UPDATE;

-- Weaker than FOR UPDATE: allows inserts into child tables
-- that reference this row via a foreign key
SELECT * FROM "Orders" WHERE "Id" = @id FOR NO KEY UPDATE;

-- Shared lock - multiple transactions can hold it simultaneously
SELECT * FROM "Orders" WHERE "Id" = @id FOR SHARE;

-- Fail immediately instead of waiting
SELECT * FROM "Orders" WHERE "Id" = @id FOR UPDATE NOWAIT;

-- Skip locked rows (great for job queues)
SELECT * FROM "Orders" WHERE "Status" = 'Pending'
FOR UPDATE SKIP LOCKED LIMIT 1;

A practical tip most people miss: if you're locking a parent row (say, an Order) while inserting child rows into another table that references it (say, OrderLines in a different transaction), prefer FOR NO KEY UPDATE. Plain FOR UPDATE blocks those inserts because inserting a referencing row needs a key-share lock on the parent.

FOR UPDATE NOWAIT is useful when you'd rather fail fast than block. SKIP LOCKED deserves its own section.

SKIP LOCKED for Job Queues

SKIP LOCKED turns a plain table into a competing-consumers job queue. Each worker locks and processes a different row, and nobody waits on anybody:

public async Task<Order?> DequeueNextOrder(AppDbContext context)
{
    await using var transaction = await context.Database
        .BeginTransactionAsync();

    var order = await context.Orders
        .FromSqlRaw(
            @"SELECT * FROM ""Orders""
              WHERE ""Status"" = 'Pending'
              ORDER BY ""CreatedAt""
              FOR UPDATE SKIP LOCKED
              LIMIT 1")
        .FirstOrDefaultAsync();

    if (order is not null)
    {
        order.Status = OrderStatus.Processing;
        await context.SaveChangesAsync();
    }

    await transaction.CommitAsync();
    return order;
}

Multiple workers can call this concurrently. Each one gets a different row - no conflicts, no retries, no duplicate processing.

This is exactly how you scale a transactional outbox processor across multiple instances. Each instance grabs its own batch of outbox messages with SKIP LOCKED, and the rows locked by one instance are invisible to the others.

One gotcha: keep the processing inside the transaction short. The row stays locked until you commit, so if your handler calls a slow external API while holding the lock, you're serializing on that API call. For long-running work, mark the row as Processing in one short transaction, commit, then do the work.

Advisory Locks

Sometimes you need to lock a concept rather than a row. Maybe the row doesn't exist yet (preventing duplicate user registration), or the thing you're protecting isn't in the database at all (a file, an external API).

PostgreSQL advisory locks let you lock an arbitrary 64-bit integer key:

public async Task<bool> TryAcquireAdvisoryLock(
    AppDbContext context, long lockKey)
{
    var result = await context.Database
        .SqlQuery<bool>(
            $"SELECT pg_try_advisory_xact_lock({lockKey}) AS \"Value\"")
        .FirstAsync();

    return result;
}

pg_try_advisory_xact_lock returns true if the lock was acquired, false if another session holds it. The _xact_ variant is the one you want with connection pooling: it releases automatically when the transaction ends, so a returned pooled connection can never carry a forgotten lock.

Use advisory locks for things like:

• Preventing duplicate processing of the same event
• Ensuring only one instance runs a scheduled job
• Coordinating access to external resources

public async Task ProcessEvent(Guid eventId)
{
    await using var transaction = await context.Database
        .BeginTransactionAsync();

    var lockKey = BitConverter.ToInt64(eventId.ToByteArray(), 0);

    if (!await TryAcquireAdvisoryLock(context, lockKey))
    {
        return; // Another process is handling this event
    }

    // Safe to process - we hold the lock
    await HandleEvent(eventId);
    await transaction.CommitAsync();
}

Deriving the key from the first 8 bytes of a Guid loses information, so two different GUIDs could theoretically map to the same key. If that happens, the two operations serialize behind one lock. You lose some throughput, and correctness is unaffected.

Advisory locks are also the foundation for distributed locking in .NET when you don't want to bring in Redis or another external system.

Bounding Wait Times With lock_timeout

By default, a blocked FOR UPDATE waits forever. In a web request, that means a hung request and a consumed connection.

Set lock_timeout inside the transaction with SET LOCAL, so it applies only to that transaction and resets automatically:

await using var transaction = await context.Database
    .BeginTransactionAsync();

await context.Database.ExecuteSqlRawAsync(
    "SET LOCAL lock_timeout = '5s'");

// Throws after 5 seconds of waiting instead of hanging
var order = await GetOrderForUpdate(context, orderId);

Prefer SET LOCAL over plain SET. A plain SET changes the session, and with Npgsql connection pooling you don't want session-level settings escaping the code that made them.

Isolation Levels and Row Locks

You can combine explicit row locks with a transaction isolation level:

await using var transaction = await context.Database
    .BeginTransactionAsync(IsolationLevel.Serializable);

Here's how PostgreSQL's isolation levels compare:

• Read Committed (the default): each statement sees data committed before that statement started. Non-repeatable reads and phantoms are possible.
• Repeatable Read: the whole transaction sees a snapshot from its start. In PostgreSQL this also prevents phantom reads, which the SQL standard doesn't require at this level.
• Serializable: transactions behave as if they ran one at a time. PostgreSQL aborts transactions that would violate serializability, so you must be prepared to retry.

For most locking scenarios, ReadCommitted combined with SELECT FOR UPDATE is sufficient. Serializable gives you the strongest guarantees without explicit locks, but you pay with retry logic for serialization failures.

Avoiding Deadlocks

Deadlocks occur when two transactions lock rows in opposite order. Transaction A locks row 1, transaction B locks row 2, then A tries to lock row 2 while B tries to lock row 1. PostgreSQL detects this and kills one of the transactions with error 40P01.

The main defense: lock rows in a deterministic order.

// Always lock rows in a consistent order
var orders = await context.Orders
    .FromSqlInterpolated(
        $@"SELECT * FROM ""Orders""
           WHERE ""Id"" = ANY({orderIds})
           ORDER BY ""Id""
           FOR UPDATE")
    .ToListAsync();

Other deadlock prevention tips:

• Keep transactions short - acquire locks, do the work, commit
• Use FOR UPDATE NOWAIT to fail fast instead of waiting indefinitely
• Set a lock_timeout to bound wait times
• Don't mix lock acquisition with slow I/O (external HTTP calls, file access)

Choosing the Right Tool

Choose between the options from the contention model:

• Optimistic concurrency: conflicts are rare, retries are cheap, you want maximum throughput. See optimistic locking in EF Core.
• FOR UPDATE: conflicts are frequent on specific rows, and the operation isn't safely retryable (payments, inventory decrements).
• SKIP LOCKED: multiple workers competing for rows in a queue-like table.
• Advisory locks: the thing you're protecting isn't a row - singleton jobs, external resources, "create if not exists" flows.

Summary

Acquire row locks inside an explicit transaction and keep the protected work as short as possible. Use SKIP LOCKED for workers competing over queue-like rows and transaction-scoped advisory locks for concepts that have no row to lock. Bound wait time and acquire multiple locks in a consistent order so contention fails predictably instead of becoming a deadlock.

Two users load the same record. Both edit it. Both hit save.

Without a concurrency token, the second write silently overwrites the first, and nobody finds out until the data looks wrong. The usual fix is adding a Version column and remembering to configure it on every entity.

But if you run PostgreSQL, you already have a version number on every row. It is called xmin, and EF Core can use it as a concurrency token with zero schema changes.

What Is xmin in PostgreSQL?

PostgreSQL uses multi-version concurrency control (MVCC). Every update creates a new physical version of the row instead of overwriting it in place.

Each row version carries hidden system columns, and one of them is xmin: the ID of the transaction that created this version of the row. Update the row, and the new version gets a new xmin.

You can see it yourself:

SELECT xmin, id, name FROM products WHERE id = 1;

-- xmin  | id | name
-- 74821 | 1  | Keyboard

UPDATE products SET name = 'Mechanical Keyboard' WHERE id = 1;

SELECT xmin, id, name FROM products WHERE id = 1;

-- xmin  | id | name
-- 74822 | 1  | Mechanical Keyboard

The value changed because the update ran in a new transaction. That is exactly the behavior you want from a row version: it changes on every write, and you do not have to maintain it.

Mapping xmin in EF Core

The Npgsql provider has first-class support for this. Add a uint property to your entity and configure it as a row version:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }

    public uint Version { get; set; }
}

Then in OnModelCreating:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Product>()
        .Property(p => p.Version)
        .IsRowVersion();
}

When the Npgsql provider sees a uint property configured as a row version, it maps it to the xmin system column instead of creating a real column.

Now generate a migration:

dotnet ef migrations add MapXminConcurrencyToken

The migration is empty. There is no schema change because the column already exists on every table. That is the whole point: you get optimistic concurrency on legacy tables, on databases you share with other applications, and on tables you are not allowed to alter.

What EF Core Does With It

Once mapped, EF Core includes the token in every UPDATE and DELETE:

UPDATE products
SET name = @p0, price = @p1
WHERE id = @p2 AND xmin = @p3
RETURNING xmin;

The RETURNING clause reads the new xmin back, so the tracked entity carries the fresh version after a successful save. If another transaction updated the row after you read it, xmin no longer matches. The WHERE clause matches zero rows, EF Core sees zero rows affected, and SaveChangesAsync throws a DbUpdateConcurrencyException.

Handling it looks like this:

try
{
    product.Price = newPrice;
    await dbContext.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
    // Someone else changed the row since we read it.
    // Reload, re-apply, or surface a conflict to the caller.
    return Results.Conflict("The product was modified by another user.");
}

For a full walkthrough of the retry-and-merge strategies, see my post on solving race conditions with EF Core optimistic locking. The mechanics are identical. The only difference is that here the token is maintained by Postgres itself.

The Disconnected Scenario

The typical web flow is disconnected: you send the row (including its version) to the client, the user edits it, and the update comes back in a later request with a fresh DbContext.

The trick is telling EF Core what the original version was when you read the entity, not what it is now:

app.MapPut("/products/{id}", async (
    int id,
    UpdateProductRequest request,
    AppDbContext dbContext) =>
{
    var product = await dbContext.Products.FindAsync(id);

    if (product is null)
    {
        return Results.NotFound();
    }

    product.Name = request.Name;
    product.Price = request.Price;

    // The version the client originally read
    dbContext.Entry(product)
        .Property(p => p.Version)
        .OriginalValue = request.Version;

    try
    {
        await dbContext.SaveChangesAsync();
        return Results.NoContent();
    }
    catch (DbUpdateConcurrencyException)
    {
        return Results.Conflict();
    }
});

Setting OriginalValue makes EF Core send the client's version in the WHERE clause. If anyone saved between the client's read and this write, the update fails and you return 409 Conflict.

The Version property serializes as a plain number, so it travels through your API contract like any other field. This pairs well with idempotent REST APIs, where the client is expected to participate in conflict handling anyway.

Caveats You Should Know

xmin is free, but it is not identical to a version column you own. Three things to keep in mind:

Any write bumps it, not just yours. Triggers, batch jobs, another service touching the same table, even an UPDATE that sets a column your entity does not map. All of them change xmin. With a hand-rolled version column, you decide what counts as a conflicting change. With xmin, every write conflicts. In practice this is usually the behavior you want, but it can produce conflicts on writes you consider irrelevant.

It is a 32-bit transaction ID. xmin is not a monotonic counter you should store long-term or compare for ordering. Transaction IDs wrap around, and PostgreSQL's freezing process is designed around that. Use it as an opaque token: read it, send it back, compare for equality. Do not build audit logic on top of it.

It is Postgres-only. If your codebase targets multiple providers (SQL Server and PostgreSQL side by side, for example), you need provider-specific model configuration. SQL Server has rowversion for the same job, but the property type differs (byte[] vs uint), so the entity cannot be identical across providers without some mapping gymnastics.

When I Still Add My Own Version Column

xmin is my default for Postgres because zero schema changes is a real advantage. Use an explicit column instead when:

• I need the version to survive export and import. xmin values are physical to the database instance, so restoring data elsewhere resets them. A real column travels with the data.
• I want conflict detection scoped to specific fields. EF Core also supports IsConcurrencyToken() on individual properties, which detects conflicting changes only where they matter.
• The domain needs a meaningful version number (an aggregate version in event sourcing, an ETag you control). A system column cannot carry business meaning.

If none of those apply, the hidden column Postgres already maintains does the job with less code and no migration. And if optimistic concurrency does not fit your write patterns at all, the alternative is pessimistic locking with EF Core and PostgreSQL, which blocks the conflict instead of detecting it.

Summary

PostgreSQL versions every row for its own MVCC machinery, and the Npgsql EF Core provider lets you piggyback on that with a single uint property and an IsRowVersion() call. You get last-write-wins protection with an empty migration, which makes it the cheapest concurrency token you will ever add.

Know the caveats: every write conflicts, the value is opaque and instance-local, and it does not port to other databases. For most Postgres-backed applications, none of that matters, and the five lines of mapping code are all you need.

Set the client's version as OriginalValue in disconnected scenarios, catch DbUpdateConcurrencyException, return 409 Conflict, and move on to the next feature.

You build an aggregate in memory: an Order with ten OrderLine children. With identity columns, none of those objects has a real id until SaveChanges returns, because the database generates the value during the insert.

Most of the time EF Core hides this from you. But the moment you need the id before saving (for an outbox message, a domain event, a log line, a reference from an object EF does not manage), the default strategy becomes a constraint. Identity, sequence, and HiLo differ in one dimension more than any other: when the id becomes known.

Identity: The Default

On SQL Server, an int or long key maps to an IDENTITY column by default. On PostgreSQL, Npgsql uses GENERATED BY DEFAULT AS IDENTITY:

public class Order
{
    public long Id { get; set; }   // identity by convention
    public List<OrderLine> Lines { get; set; } = [];
}

The id is born inside the INSERT. EF Core appends a RETURNING / OUTPUT clause to read it back, then runs relationship fixup: it patches the real ids into tracked children's foreign keys and inserts them in dependency order.

That machinery is why identity feels free. It also has consequences:

• Before SaveChanges, order.Id is 0. Temporary negative ids exist only inside the change tracker.
• Inserts of parent-child graphs must be ordered (parents first), constraining how EF batches statements.
• Every insert round trip carries the overhead of returning generated values.

For most CRUD workloads, none of this matters. It starts to matter in outbox and event patterns, where you want to serialize an event containing order.Id in the same unit of work, ideally without contorting your code to run after the save. The transactional outbox gets much cleaner when ids exist up front.

Sequence: Identity Timing, More Flexibility

A sequence is a standalone database object, decoupled from any table. EF Core 7+ supports it directly on SQL Server:

modelBuilder.Entity<Order>()
    .Property(o => o.Id)
    .UseSequence("OrderIds");

The migration creates the sequence and gives the key column a default constraint of NEXT VALUE FOR [OrderIds], so the database still generates the value during the insert and EF Core reads it back, exactly like identity. A sequence alone does not give you ids any earlier. What it does give you:

• Shared ranges. Multiple tables can draw from one sequence, guaranteeing ids unique across tables (useful for table-per-concrete-type inheritance mappings).
• No identity semantics on the column. Plain inserts with explicit ids, no IDENTITY_INSERT dance when migrating data.
• Tunable caching on the database side (CACHE 50) to cut sequence round trips.

Think of sequences as the infrastructure HiLo builds on.

HiLo: Ids Before SaveChanges

HiLo splits id generation between database and client. The database sequence hands out high values; the application turns each high value into a block of ids and assigns the low values itself.

modelBuilder.Entity<Order>()
    .Property(o => o.Id)
    .UseHiLo("OrderHiLo");

modelBuilder.Entity<OrderLine>()
    .Property(l => l.Id)
    .UseHiLo("OrderLineHiLo");

The migration creates sequences with an increment of 10 (the default block size). When you Add the first entity, EF Core fetches one sequence value and now owns ids, say, 41 through 50, assignable with zero database contact.

The payoff is immediate and visible:

var order = new Order();
context.Orders.Add(order);

Console.WriteLine(order.Id); // real, final id. SaveChanges has NOT run.

var outboxMessage = OutboxMessage.From(
    new OrderCreatedEvent(order.Id)); // safe: the id is real

context.Add(outboxMessage);
await context.SaveChangesAsync();

Two things just became possible:

• Foreign keys on unsaved graphs. You can wire up references between new objects by id, not just by navigation property, including references from things EF does not track (serialized events, cache keys, messages).
• Leaner batch inserts. Since ids are known, EF Core sends plain inserts without needing generated keys back, and insert ordering constraints relax. On graphs of thousands of new rows this measurably reduces save time, though for true bulk loads SqlBulkCopy-style APIs still win by an order of magnitude, as I showed in fast SQL bulk inserts.

The costs are mostly aesthetic and operational:

• Gaps. An app instance that reserved ids 41-50 and restarted after using 41 discards nine ids. Sequences also produce gaps on rollback. If anyone in your organization believes invoice numbers must be gap-free, ids are the wrong place for that requirement anyway; model document numbers separately.
• Block size tuning. Increment 10 means a sequence round trip every 10 inserts per instance. High-throughput insert paths want a bigger block; you set it by configuring the sequence's increment and matching it in UseHiLo's sequence definition.
• Provider support. SQL Server and PostgreSQL support HiLo well through their EF providers.

What About GUIDs?

Client-generated GUIDs solve the same "id before save" problem with zero database coordination:

public class Order
{
    public Guid Id { get; set; } = Guid.CreateVersion7();
}

Random Version 4 GUIDs fragment clustered indexes badly, which is the historical argument for HiLo. .NET 9's Guid.CreateVersion7() produces time-ordered values that insert nearly sequentially, removing most of that objection. I compared the index behavior in detail in GUID v7 in .NET.

The remaining tradeoff is size and ergonomics: 16 bytes versus 8, and integer ids stay friendlier in URLs, logs, and support conversations. If you were reaching for HiLo purely to get ids before save, UUIDv7 is the simpler modern answer. If you want small sequential integers and early ids, HiLo remains the only game in town.

Choosing

• Default CRUD app, ids never needed pre-save: identity. Zero configuration, everyone understands it.
• Ids needed before SaveChanges (outbox, domain events, cross-aggregate references): HiLo for integer keys, UUIDv7 for GUID keys.
• Heavy graph inserts through EF Core: HiLo; it strips the returning overhead and ordering constraints. Combine with the batching guidance from optimizing bulk database updates.
• Unique ids across several tables, data migrations with explicit ids: sequence.
• Distributed id generation across services: none of these; use UUIDv7 or an id service. Database-coordinated strategies stop at the database boundary.

One migration note: switching strategies on an existing table is a real schema change (dropping identity, creating sequences, seeding the sequence past the current max id). Plan it like any other risky migration, and rehearse against a production-sized copy.

Summary

The three strategies answer one question differently: when do you learn the id? Identity and sequences answer "after the insert", and HiLo answers "the moment you Add the entity", because the application owns a reserved block of ids.

That timing difference is not a micro-optimization. Ids known before SaveChanges are what make outbox messages, domain events, and references across unsaved graphs clean to implement, and they let EF Core batch inserts without reading keys back.

Use identity until you feel the constraint. When you do, reach for HiLo if you value compact integer keys, or UUIDv7 if you value zero coordination. Both give you the id exactly when the interesting patterns need it: before the save.

Delete an order and its order lines should go with it. Every ORM promises this, EF Core delivers it, and most developers stop reading there.

Then one day a delete that always worked starts throwing foreign key violations, but only in production, and only for some rows. The root cause is almost always the same: DeleteBehavior configures two different mechanisms, one in EF's memory and one in the database, and they do not have to agree.

The Two Mechanisms

When you delete a principal (the Order), something has to happen to its dependents (the OrderLine rows holding the foreign key). Two independent actors can handle it:

EF Core, in memory. The change tracker knows about the entities it is tracking. If you delete an order while its lines are loaded and tracked, EF marks the lines Deleted too and issues DELETE statements for them, children first, in the right order.

The database, via the foreign key constraint. The migration generates ON DELETE CASCADE (or SET NULL, or NO ACTION) on the FK. The database then handles dependents for every delete, including rows EF has never seen.

Here is the point the documentation makes quietly and bugs make loudly: EF's in-memory cascade only applies to tracked entities. If the lines are not loaded, EF sends one DELETE for the order and hopes the database handles the rest. Whether it does depends entirely on what constraint the migration created.

What Does DeleteBehavior Actually Map To?

Each DeleteBehavior value answers both questions at once: what EF does to tracked dependents, and what DDL the migration generates.

• Cascade: EF deletes tracked dependents, and the database gets ON DELETE CASCADE. Both actors cascade. Unloaded dependents are handled by the database.
• ClientCascade: EF deletes tracked dependents, but the database gets NO ACTION/RESTRICT. If any dependent is not loaded when you delete the principal, the database throws an FK violation.
• SetNull: the database gets ON DELETE SET NULL, and EF nulls the FK on tracked dependents. Only valid for optional (nullable FK) relationships.
• ClientSetNull (the default for optional relationships): EF nulls the FK on tracked dependents, the database gets NO ACTION. Same trap as ClientCascade, with nulling instead of deleting.
• Restrict / NoAction: nobody cascades. EF will even throw at SaveChanges if you leave tracked dependents orphaned. Deleting a principal with existing dependents is an error unless you handle the dependents yourself first.

And the conventions that decide which one you get when you configure nothing:

• Required relationship (non-nullable FK): Cascade.
• Optional relationship (nullable FK): ClientSetNull.

Configuration lives in OnModelCreating, per relationship:

modelBuilder.Entity<Order>()
    .HasMany(o => o.Lines)
    .WithOne(l => l.Order)
    .HasForeignKey(l => l.OrderId)
    .OnDelete(DeleteBehavior.Cascade);

If you take one sentence from this article: the Client* behaviors mean the database will not help you, and any delete that touches unloaded dependents will fail with an FK violation.

The Classic Failure, Step by Step

This is the "works in tests, fails in production" bug.

Say the relationship between Blog and Post is configured as ClientCascade, or it is optional and got the default ClientSetNull. Now delete a blog by id without loading its posts:

var blog = await dbContext.Blogs.FirstAsync(b => b.Id == blogId);

dbContext.Blogs.Remove(blog);

await dbContext.SaveChangesAsync();
// PostgresException: 23503: update or delete on table "Blogs"
// violates foreign key constraint "FK_Posts_Blogs_BlogId" on table "Posts"

In your test, the blog had no posts (or you had them loaded from an earlier assertion), so it passed. If the blog has 400 posts that EF never loaded, the database sees a bare DELETE FROM Blogs, and the NO ACTION constraint rejects it. (On SQL Server the same failure surfaces as a SqlException about a conflicted REFERENCE constraint.)

Three legitimate fixes, in order of my preference:

// 1. Let the database own it: switch to DeleteBehavior.Cascade
//    (migration adds ON DELETE CASCADE).

// 2. Delete dependents explicitly with a set-based query first.
await dbContext.Posts
    .Where(p => p.BlogId == blogId)
    .ExecuteDeleteAsync();

await dbContext.Blogs
    .Where(b => b.Id == blogId)
    .ExecuteDeleteAsync();

// 3. Load the graph so EF's client cascade has something to work on.
var blog = await dbContext.Blogs
    .Include(b => b.Posts)
    .FirstAsync(b => b.Id == blogId);

dbContext.Blogs.Remove(blog); // posts marked Deleted too
await dbContext.SaveChangesAsync();

Option 3 is the one to be suspicious of: loading 400 rows to delete them is pure waste. Note that ExecuteDeleteAsync bypasses the change tracker entirely, so with it, client-side behaviors never run and only the database constraint matters. If you use bulk deletes, your delete behavior IS your DDL, full stop. And when a delete spans multiple statements like option 2, wrap it in a transaction.

Why ClientCascade Exists at All: SQL Server's Cascade Paths

If Cascade is the honest behavior, why would anyone choose ClientCascade?

Because SQL Server refuses some cascades. Create a schema where the same table is reachable through two ON DELETE CASCADE chains (a diamond), and the migration fails with:

Msg 1785: Introducing FOREIGN KEY constraint 'FK_...' on table '...'
may cause cycles or multiple cascade paths.
Specify ON DELETE NO ACTION or ON UPDATE NO ACTION,
or modify other FOREIGN KEY constraints.

The standard example: Customer has Orders, Customer has Addresses, and Order references Address. Deleting a customer can reach the order both directly and through the address, and SQL Server will not create the second cascade. PostgreSQL, for the record, allows this happily; it is a SQL Server limitation, and it is one of the behavioral differences worth knowing if you work across PostgreSQL and SQL Server.

Your options when you hit error 1785:

• Break one edge of the diamond with DeleteBehavior.Restrict or NoAction and delete that path explicitly in code.
• Use ClientCascade on that edge: EF still cascades tracked graphs, and you accept the load-before-delete obligation documented above.
• Reconsider whether both relationships should be required. Often one of them is really optional, and SetNull dissolves the diamond.

ClientCascade is a workaround with a maintenance contract attached, not a default to reach for.

Cascades and Aggregates: Being Deliberate

My actual rule for choosing behaviors has less to do with EF and more with domain design:

Cascade inside an aggregate, restrict between aggregates.

OrderLine has no life without its Order: cascade, and let the database enforce it. But Order referencing Customer is a relationship between aggregates, and silently vaporizing a customer's orders because someone deleted the customer is a catastrophe, not a convenience. That edge gets Restrict, and "delete a customer" becomes an explicit use case that decides what happens to orders. This mapping between aggregate boundaries and FK behaviors is a recurring theme in modeling aggregates with EF Core, and it is the lens I teach in Pragmatic Domain-Driven Design.

Two pitfalls to close the loop on:

Soft delete changes everything. If Order is soft-deleted (an IsDeleted flag plus a query filter), a database ON DELETE CASCADE is now a landmine: the parent row never gets a SQL DELETE in normal operation, but any hard delete (cleanup jobs, GDPR erasure) will physically cascade to children you meant to keep as soft-deleted history. Soft-deleted aggregates should pair with Restrict semantics and propagate the flag explicitly to dependents.

Verify the DDL, not the C#. The delete behavior you configured is a claim; the migration is the truth. Read the generated migration (or the SQL from dotnet ef migrations script) and confirm the onDelete: values match your intent, the same way you would review any migration before it ships.

Summary

• DeleteBehavior sets two things at once: EF's handling of tracked dependents and the ON DELETE clause in your schema. Bugs live in the gap between them.
• Cascade means the database covers unloaded rows. ClientCascade and ClientSetNull mean it does not, and deletes fail the moment dependents exist that EF has not loaded.
• ExecuteDeleteAsync skips the change tracker, so only the database behavior applies to it.
• SQL Server's multiple-cascade-paths error is the main legitimate reason ClientCascade exists. Prefer breaking the diamond with Restrict plus explicit deletes.
• Design rule: cascade within an aggregate, restrict between aggregates, and never mix database cascades with soft delete without deciding exactly what a hard delete should destroy.

Cascade delete is not one feature. It is a contract between your code and your schema, and it only works when both sides say the same thing.

Product categories nest. Org charts nest. Comment threads, folder structures, chart-of-accounts, all of them are trees, and sooner or later you have to persist one in a relational database.

The natural model in EF Core, a self-referencing entity with a ParentId, takes five minutes to write. Then you try to load a subtree, or delete a node, or find every descendant of "Electronics", and discover that the write model and the read patterns are at war.

The adjacency list works well when its self-referencing relationship and read strategy are explicit. The two escalation paths, recursive CTEs and PostgreSQL ltree, become useful when the tree gets large.

The Adjacency List

An adjacency list stores a tree in one table by giving every row a foreign key that points at its parent. Roots have a null parent:

public class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;

    public int? ParentId { get; set; }
    public Category? Parent { get; set; }
    public List<Category> Children { get; set; } = [];
}

The configuration deserves care, especially the delete behavior:

public class CategoryConfiguration : IEntityTypeConfiguration<Category>
{
    public void Configure(EntityTypeBuilder<Category> builder)
    {
        builder.HasOne(c => c.Parent)
            .WithMany(c => c.Children)
            .HasForeignKey(c => c.ParentId)
            .OnDelete(DeleteBehavior.Restrict);

        builder.HasIndex(c => c.ParentId);
    }
}

Two deliberate choices:

• DeleteBehavior.Restrict. SQL Server rejects cascade on self-referencing foreign keys outright (cycle detection), and even on PostgreSQL, where it works, cascading a node delete into silently vaporizing a subtree is rarely what the business meant. Make subtree deletion an explicit operation. The broader reasoning is in cascade delete in EF Core.
• An index on ParentId. Every children lookup filters on it. Skipping this index is the most common hierarchy performance bug I see.

How Do You Load a Whole Tree Without N+1 Queries?

One level is easy:

var roots = await context.Categories
    .Where(c => c.ParentId == null)
    .Include(c => c.Children)
    .ToListAsync();

The trap is trying to go deeper with chained includes (.Include(c => c.Children).ThenInclude(c => c.Children) and so on). That hardcodes a maximum depth, and each level multiplies the join. The recursive-lazy-loading variant is worse: walking Children with lazy loading fires one query per node, the classic shape from the N+1 query problem.

For hierarchies of reasonable size (navigation menus, category trees, org units, anything up to a few thousand rows), the right move is almost embarrassingly simple: load the whole set in one query and let relationship fixup build the tree.

var all = await context.Categories.ToListAsync();

var roots = all.Where(c => c.ParentId is null).ToList();

When EF Core materializes the rows, identity resolution connects every Parent and Children navigation automatically. One SELECT, and roots is a fully wired object graph you can recurse in memory. This works with tracking queries, and with AsNoTrackingWithIdentityResolution if you do not need tracking. Plain AsNoTracking skips identity resolution, so the rows materialize as disconnected objects and the navigations stay unwired.

Scope the query if the table holds many independent trees:

var all = await context.Categories
    .Where(c => c.TreeId == treeId)
    .ToListAsync();

Recursive CTEs: Push the Recursion into the Database

When the hierarchy has hundreds of thousands of rows and you need one subtree, loading everything stops being cute. Relational databases walk hierarchies natively with recursive CTEs, and EF Core consumes them cleanly through SqlQuery or FromSqlRaw:

var subtree = await context.Database
    .SqlQuery<CategoryRow>($"""
        WITH RECURSIVE subtree AS (
            SELECT "Id", "Name", "ParentId"
            FROM "Categories"
            WHERE "Id" = {rootId}

            UNION ALL

            SELECT c."Id", c."Name", c."ParentId"
            FROM "Categories" c
            JOIN subtree s ON c."ParentId" = s."Id"
        )
        SELECT "Id", "Name", "ParentId" FROM subtree
        """)
    .ToListAsync();

(That is PostgreSQL syntax; SQL Server drops the RECURSIVE keyword and brackets the identifiers. One SQL Server catch: SqlQuery composes over your SQL as a subquery, and T-SQL does not allow a CTE inside one, so use FromSql on a mapped entity there instead.)

The same pattern answers the other classic questions: the ancestor chain of a node (flip the join direction), the depth of each node (carry a level + 1 column through the recursion), and "does moving node X under node Y create a cycle" (check whether Y appears in X's descendants).

This is one of the places where dropping to SQL is not a failure of the ORM, it is using each tool for what it is good at. I covered the mechanics and parameterization safety in EF Core raw SQL queries.

PostgreSQL ltree: Materialized Paths with an Index

If your workload is read-heavy on subtrees, PostgreSQL's ltree extension changes the data structure itself. Each node stores its full path as a chain of labels (electronics.computers.laptops), and a GiST index makes subtree and ancestor queries indexed operations instead of recursion.

Npgsql maps the LTree type directly:

public class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public LTree Path { get; set; }
}

// in OnModelCreating
modelBuilder.HasPostgresExtension("ltree");

modelBuilder.Entity<Category>()
    .HasIndex(c => c.Path)
    .HasMethod("gist");

Subtree and ancestor queries become one-liners that translate to indexed operators:

// all descendants of electronics.computers
var descendants = await context.Categories
    .Where(c => c.Path.IsDescendantOf(new LTree("electronics.computers")))
    .ToListAsync();

// ancestors of a node
var ancestors = await context.Categories
    .Where(c => new LTree("electronics.computers.laptops").IsDescendantOf(c.Path))
    .ToListAsync();

The cost shows up on writes: moving a subtree means rewriting the Path of every descendant, and the application owns path maintenance (nothing enforces that electronics.computers exists just because a path mentions it). Many teams run ltree alongside a ParentId, treating the path as a derived, indexed acceleration structure. If you are Postgres-curious about features like this, PostgreSQL vs SQL Server for .NET developers covers more of what you gain.

SQL Server's counterpart is hierarchyid, supported in EF Core 8+ via Microsoft.EntityFrameworkCore.SqlServer.HierarchyId, with similar tradeoffs.

Choosing a Hierarchy Strategy

• Small tree, read whole or nearly whole (menus, categories, org units under ~5k rows): adjacency list, load-all plus fixup. Simplest code, one query, done.
• Large tree, occasional subtree or ancestor queries: adjacency list plus recursive CTEs for the heavy questions.
• Large tree, subtree queries on the hot path, rare moves: ltree (or hierarchyid) with a GiST index, likely alongside the adjacency columns.
• Comment threads and event-like data that only append: adjacency list; threads are shallow and append-only, recursion rarely hurts.

Summary

The adjacency list is the right default: it is normalized, enforces referential integrity, and EF Core's relationship fixup gives you an underrated superpower, load the rows in one query and get a fully connected tree for free. Configure Restrict on the self-reference, index ParentId, and never chain ThenInclude to fake recursion.

When the tree outgrows load-everything, do not fight LINQ into recursion it cannot express. Recursive CTEs answer subtree, ancestor, and depth questions inside the database, and Postgres ltree turns subtree reads into indexed lookups when they dominate your workload.

Pick the structure by the queries you run, not by the shape of the data. Trees are all shaped the same; workloads are not.

Open any mature EF Core codebase and count how many times HasMaxLength(200) appears. Then HasPrecision(18, 2). Then the same DateTime UTC converter, pasted into every configuration class that touches a timestamp.

Every one of those lines is a default pretending to be a decision. And every new entity is a chance to forget one, which is how you end up with an unbounded nvarchar(max) column holding a two-letter country code.

EF Core has a proper answer: conventions. Set the default once, override it only where the entity genuinely differs.

ConfigureConventions: Defaults by Type

Override ConfigureConventions in your DbContext. It runs before the model is built, and everything it sets acts as a default that individual configurations can still override:

public class AppDbContext(DbContextOptions<AppDbContext> options)
    : DbContext(options)
{
    protected override void ConfigureConventions(
        ModelConfigurationBuilder configurationBuilder)
    {
        configurationBuilder.Properties<string>()
            .HaveMaxLength(500);

        configurationBuilder.Properties<decimal>()
            .HavePrecision(18, 2);

        configurationBuilder.Properties<Enum>()
            .HaveConversion<string>()
            .HaveMaxLength(50);
    }
}

Three calls, and the entire model now has:

• No accidental nvarchar(max) columns. Every string is capped at 500 unless someone consciously raises it.
• Consistent money precision. No more silent truncation because one configuration said (18, 2) and another said nothing.
• Every enum stored as a readable string, a choice I unpack in mapping enums in EF Core.

Per-entity configuration still wins, which is exactly what you want:

builder.Property(p => p.Description).HasMaxLength(4000);

The default handles the 90 percent case; the override documents the exception.

Model-Wide Value Converters

A broadly useful convention is a type-wide value converter. The classic example is enforcing UTC for every DateTime, which also addresses the Npgsql timestamptz Kind error:

public class UtcDateTimeConverter : ValueConverter<DateTime, DateTime>
{
    public UtcDateTimeConverter()
        : base(
            v => v.Kind == DateTimeKind.Utc ? v : v.ToUniversalTime(),
            v => DateTime.SpecifyKind(v, DateTimeKind.Utc))
    {
    }
}

Registered once for the whole model:

protected override void ConfigureConventions(
    ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<DateTime>()
        .HaveConversion<UtcDateTimeConverter>();
}

The same mechanism registers converters for strongly typed IDs and value objects. If you wrap identifiers in types like OrderId, one Properties<OrderId>().HaveConversion<OrderIdConverter>() beats fifty per-property calls. I covered the converter side of this in value conversions in EF Core.

Can You Remove a Built-In Convention?

Conventions are not just additive. configurationBuilder.Conventions exposes the full convention set, and you can remove the ones you disagree with.

The one I remove most often is cascade delete for required relationships:

protected override void ConfigureConventions(
    ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Conventions.Remove(typeof(CascadeDeleteConvention));

    // Only exists (and is only needed) on the SQL Server provider
    configurationBuilder.Conventions.Remove(typeof(SqlServerOnDeleteConvention));
}

With those gone, deletes fail loudly instead of fanning out silently, and every cascade in the schema is one someone chose. Whether you want that depends on how you feel about the tradeoffs in cascade delete in EF Core, but the point stands: the built-in defaults are opinions, and you are allowed to override them.

Custom Convention Classes for Everything Else

ConfigureConventions handles type-based defaults. For rules that depend on names, attributes, or model structure, EF Core 7+ lets you write real convention classes.

IModelFinalizingConvention is the workhorse: it runs once, right before the model is finalized, with the whole model available for inspection and mutation. Here is one that caps any string property whose name ends in Code at 20 characters:

public class CodePropertyLengthConvention : IModelFinalizingConvention
{
    public void ProcessModelFinalizing(
        IConventionModelBuilder modelBuilder,
        IConventionContext<IConventionModelBuilder> context)
    {
        foreach (var entityType in modelBuilder.Metadata.GetEntityTypes())
        {
            foreach (var property in entityType.GetDeclaredProperties())
            {
                if (property.ClrType == typeof(string) &&
                    property.Name.EndsWith("Code", StringComparison.Ordinal))
                {
                    property.Builder.HasMaxLength(20);
                }
            }
        }
    }
}

Register it in the same ConfigureConventions override:

configurationBuilder.Conventions.Add(_ => new CodePropertyLengthConvention());

Other conventions that fit this pattern:

• Table names without the pluralization the DbSet name implies.
• A global RowVersion shadow property on every aggregate root for optimistic locking.
• Snake_case column naming for PostgreSQL across the entire model.

One warning: property.Builder calls inside a convention use the convention precedence level. That is by design. It means explicit configuration and data annotations still override your convention, keeping the precedence hierarchy intact: explicit Fluent API beats attributes, attributes beat conventions.

Where Conventions Fit in Your Architecture

Conventions do not replace IEntityTypeConfiguration<T> classes. They change what those classes contain.

After adopting conventions, my per-entity configurations shrink to the things that are genuinely per-entity: keys, relationships, indexes, owned types, and the handful of properties that deviate from the defaults. The configurations become readable because everything in them is a decision, not boilerplate.

A concrete structure that has worked well for me:

• ConfigureConventions in the DbContext: type defaults (string length, precision, enum storage, UTC dates, strongly typed ID converters).
• One or two convention classes: naming rules and cross-cutting shadow properties.
• IEntityTypeConfiguration<T> per aggregate, applied with ApplyConfigurationsFromAssembly: structure and exceptions.

This keeps the persistence model boring and predictable, which is exactly what you want when the domain model is where the interesting decisions live. That separation is a core theme of Pragmatic Clean Architecture.

One operational note: conventions apply to the whole model, so introducing one on an existing database is a schema change. Adding a 500-character default to a model full of nvarchar(max) columns produces a large migration. Review it, and roll it out like any other wide migration, ideally through the practices in EF Core migrations best practices.

Summary

Repeated configuration is a smell, and EF Core gives you two tools to eliminate it. ConfigureConventions sets type-based defaults (lengths, precision, converters, enum storage) in one place, and convention classes like IModelFinalizingConvention handle name-based and structural rules the simple API cannot express.

The payoff is not just fewer lines. It is that defaults become enforced instead of remembered. A new entity added six months from now gets capped strings, correct decimal precision, UTC dates, and string enums without its author thinking about any of it, and the per-entity configuration files are left holding only real decisions.

Set the defaults once. Make every override a visible exception.

You have an OrderItem with UnitPrice and Quantity, and half your queries need the line total. Calculating it in C# works until a report queries the table directly, a bulk update skips your domain logic, or someone filters by total in SQL and gets a full table scan.

Computed columns move the calculation into the database schema. The value cannot drift because nobody writes it, the database derives it. EF Core maps them with one configuration call, but the stored flag you pass decides whether the column is just a convenience or something you can index and filter on cheaply.

Mapping a Computed Column

HasComputedColumnSql takes a SQL expression and wires the property as database-generated:

public class OrderItem
{
    public Guid Id { get; set; }
    public decimal UnitPrice { get; set; }
    public int Quantity { get; set; }
    public decimal LineTotal { get; private set; }
}

public class OrderItemConfiguration : IEntityTypeConfiguration<OrderItem>
{
    public void Configure(EntityTypeBuilder<OrderItem> builder)
    {
        builder.Property(oi => oi.LineTotal)
            .HasComputedColumnSql("[UnitPrice] * [Quantity]", stored: true);
    }
}

The migration produces a column the database owns:

ALTER TABLE [OrderItems] ADD [LineTotal] AS ([UnitPrice] * [Quantity]) PERSISTED;

A few things happen implicitly:

• The property becomes ValueGeneratedOnAddOrUpdate. EF Core never includes it in INSERT or UPDATE statements.
• After SaveChanges, EF Core reads the value back, so the in-memory entity is up to date without a manual reload.
• The private set keeps your own code honest. Assigning it does nothing useful, so make it impossible.

Note the SQL is provider-specific. [UnitPrice] is SQL Server quoting; on PostgreSQL you would write "UnitPrice" * "Quantity". If you support multiple providers, this is one of the places the abstraction leaks.

Stored vs Virtual: The Decision That Matters

The stored parameter is the whole game:

• Virtual (default, stored: false): the expression runs every time the row is read. Zero storage cost, and the value is recalculated even if you change the expression without rewriting rows. But every read pays the compute, and on SQL Server you generally cannot index it unless the expression is deterministic and precise.
• Stored / persisted (stored: true): the value is calculated on insert and update and written to disk. Reads are as cheap as any column, and you can index it.

My default is stored: true for anything used in a WHERE, ORDER BY, or JOIN. The moment you filter on a virtual computed column, the database evaluates the expression for every candidate row. That is a scan, exactly what I profile for in EF Core query performance mistakes.

Indexing a stored column is just a normal index:

builder.HasIndex(oi => oi.LineTotal);

One PostgreSQL-specific gotcha: before PostgreSQL 18, generated columns are always stored, and Npgsql throws at migration time if you leave stored: false (the default). PostgreSQL 18 adds virtual generated columns (the Npgsql provider supports them from version 10), but they cannot be indexed, so for anything you filter on the call stays:

builder.Property(oi => oi.LineTotal)
    .HasComputedColumnSql("\"UnitPrice\" * \"Quantity\"", stored: true);

A More Useful Example: Searchable Full Names

Concatenations are where computed columns earn their keep, because they make prefix searches and sorting trivial:

public class CustomerConfiguration : IEntityTypeConfiguration<Customer>
{
    public void Configure(EntityTypeBuilder<Customer> builder)
    {
        builder.Property(c => c.FullName)
            .HasComputedColumnSql("[FirstName] + ' ' + [LastName]", stored: true)
            .HasMaxLength(201);

        builder.HasIndex(c => c.FullName);
    }
}

Now this LINQ query uses the index instead of concatenating per row:

var customers = await context.Customers
    .Where(c => c.FullName.StartsWith(prefix))
    .OrderBy(c => c.FullName)
    .Take(20)
    .ToListAsync();

Without the computed column, c.FirstName + " " + c.LastName in the Where clause translates to an expression the database evaluates row by row. Same result, very different query plan.

Another PostgreSQL pattern is a generated tsvector column for search, covered in PostgreSQL full-text search with EF Core. Same mechanism, bigger payoff.

What You Cannot Do

Computed columns have hard limits, and hitting them late hurts:

• No subqueries or other tables. The expression can only reference columns of the same row. A TotalOrderValue that sums child rows is not a computed column; that is a view, a trigger, or an application-maintained value.
• Deterministic expressions only for persisted columns. GETUTCDATE() or anything nondeterministic cannot be persisted on SQL Server and cannot be a generated column on Postgres at all.
• EF Core cannot validate your SQL. The expression is an opaque string. A typo surfaces when the migration runs, not at build time. Test migrations in CI, which is one more reason I like migration bundles.
• Changing the expression is a migration. For stored columns on Postgres and persisted columns on SQL Server, altering the expression means dropping and re-adding the column, and the table rewrite that comes with it. On a large table, plan for it like any other risky migration.

Computed Column or C# Property?

Not every derived value belongs in the database. A plain C# expression-bodied property is simpler when the value never appears in a query:

public decimal LineTotal => UnitPrice * Quantity;

My decision rule:

• Only displayed, never queried: C# property. No schema, no migration, no provider-specific SQL.
• Filtered, sorted, joined, or read by other SQL consumers (reports, ETL, Dapper queries, triggers): computed column, stored, probably indexed.
• Derived from other rows or tables: neither. Use a view, a projection, or maintain it explicitly with concurrency control.

The worst option is the one teams drift into by accident: a normal column that application code tries to keep in sync. Every code path that forgets is a data bug, and bulk updates with ExecuteUpdateAsync will forget, because they bypass your domain logic entirely. A computed column is immune to that by construction: ExecuteUpdateAsync changes Quantity, and the database recalculates LineTotal in the same statement.

Summary

Computed columns hand the derivation to the only party that sees every write: the database. HasComputedColumnSql maps them in one line, EF Core treats them as read-only and refreshes them after save, and no code path, not even raw SQL or bulk updates, can make the value inconsistent.

The stored flag is the real decision. Virtual columns cost nothing to store but recompute on every read and mostly cannot be indexed. Stored columns pay a small write cost and give you indexable, filter-friendly values. On PostgreSQL, pass stored: true: generated columns are always stored before PostgreSQL 18, and the virtual ones PostgreSQL 18 adds cannot be indexed.

If the value is only ever rendered, keep it as a C# property. The database earns the job the moment the value shows up in a WHERE clause.

Not every object in your domain earns a table. User preferences, a shipping address snapshot frozen at order time, integration metadata with a shape you do not control: normalizing these into tables buys you joins and migrations without buying you anything.

Stuffing them into a string column and serializing by hand loses querying, change tracking, and type safety. JSON columns with ToJson keep all three. You get a document inside the row, and LINQ still translates into the document.

Mapping with ToJson

JSON columns build on owned types. Model the payload as a plain class, own it, and call ToJson:

public class Order
{
    public Guid Id { get; set; }
    public DateTime CreatedAtUtc { get; set; }

    public ShippingInfo Shipping { get; set; } = null!;
}

public class ShippingInfo
{
    public string Street { get; set; } = string.Empty;
    public string City { get; set; } = string.Empty;
    public string CountryCode { get; set; } = string.Empty;
    public DeliveryInstructions? Instructions { get; set; }
}

public class DeliveryInstructions
{
    public string? GateCode { get; set; }
    public bool LeaveAtDoor { get; set; }
}

The configuration is one call on the owned navigation:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.OwnsOne(o => o.Shipping, shipping =>
        {
            shipping.ToJson();
            shipping.OwnsOne(s => s.Instructions);
        });
    }
}

The resulting table has a single Shipping column of type nvarchar(max) on SQL Server or jsonb on PostgreSQL, holding the nested document. Nesting is free: Instructions lives inside the same document, no extra configuration beyond declaring the ownership.

Collections work the same way with OwnsMany:

builder.OwnsMany(o => o.StatusHistory, h => h.ToJson());

This is a natural fit for the value-object style of modeling I covered in owned types and DDD: the JSON column is an implementation detail, and the domain model stays clean C#.

Also worth knowing: since EF Core 8, primitive collections (List<string>, int[]) on an entity are mapped automatically with no configuration, stored as JSON on SQL Server and SQLite. On PostgreSQL, Npgsql maps them to native arrays instead.

Querying into the Document

This is the part that separates ToJson from a hand-rolled serialized string. LINQ translates into JSON path operations:

var orders = await context.Orders
    .Where(o => o.Shipping.City == "Oslo")
    .Where(o => o.Shipping.Instructions!.LeaveAtDoor)
    .OrderBy(o => o.Shipping.CountryCode)
    .ToListAsync();

On PostgreSQL that becomes jsonb extraction operators; on SQL Server, JSON_VALUE calls:

SELECT o."Id", o."CreatedAtUtc", o."Shipping"
FROM "Orders" AS o
WHERE (o."Shipping" ->> 'City') = 'Oslo'
  AND CAST(o."Shipping" #>> '{Instructions,LeaveAtDoor}' AS boolean)
ORDER BY o."Shipping" ->> 'CountryCode'

Projections reach inside too, so you can select just a fragment without materializing the owner:

var cities = await context.Orders
    .Select(o => o.Shipping.City)
    .Distinct()
    .ToListAsync();

The translation coverage keeps expanding with each EF release (EF 8 brought JSON collection querying so you can run Any over an OwnsMany document; EF 9 and 10 keep filling gaps). When you hit an edge the provider cannot translate, raw SQL against the same column is always available.

Partial Updates

Change tracking works through the document. Modify one property and save:

var order = await context.Orders.FirstAsync(o => o.Id == orderId);

order.Shipping.Instructions!.GateCode = "4471";

await context.SaveChangesAsync();

EF Core does not rewrite the whole document. It generates a targeted patch, JSON_MODIFY on SQL Server, jsonb_set on PostgreSQL, updating only the changed path. Small documents make this mostly a correctness nicety; on documents holding sizable collections it is a real write amplification saver.

The usual change tracker rules apply: the owned instances are tracked with their owner, and replacing the whole Shipping object marks the full document modified.

How Do You Index a Value Inside a JSON Column?

The first JSON column that ends up in a hot WHERE clause will need an index, and EF Core's fluent API stops at the column boundary. Two patterns cover it.

On SQL Server, extract the value into a computed column and index that:

builder.Property<string>("ShippingCity")
    .HasComputedColumnSql("JSON_VALUE([Shipping], '$.City')", stored: true);

builder.HasIndex("ShippingCity");

That is the same mechanism I described in computed columns in EF Core, applied to JSON extraction.

On PostgreSQL, add a GIN or expression index with raw SQL in a migration:

migrationBuilder.Sql(
    """
    CREATE INDEX ix_orders_shipping_city
    ON "Orders" ((("Shipping" ->> 'City')));
    """);

migrationBuilder.Sql(
    """
    CREATE INDEX ix_orders_shipping_gin
    ON "Orders" USING gin ("Shipping");
    """);

The expression index serves equality on one known path; the GIN index serves containment queries across arbitrary paths. More on picking between Postgres index types in PostgreSQL indexes for .NET developers.

Where JSON Columns Are the Wrong Tool

The failure mode of document-in-row is using it for things that are actually relational:

• Anything referenced by other tables. There are no foreign keys into a JSON document. If another entity needs to point at it, it is a table.
• Data queried independently of its owner at scale. Filtering ten million rows by a JSON property, even indexed, competes poorly with a proper column. Promote hot properties to real columns; keep the long tail in the document.
• Data with strong schema guarantees. The database will happily store a document missing half its fields. Your C# types constrain what your app writes, not what exists.
• Concurrent partial edits from multiple writers. Two processes editing different parts of the same document still conflict at the row level. If that is your workload, split the document or handle it with optimistic concurrency.

My heuristic: JSON columns hold data that lives and dies with its row, varies in shape, and is queried mostly through its owner. Addresses-as-snapshots, settings, metadata, denormalized read models. Everything else stays relational.

Summary

ToJson turns owned types into JSON documents inside a relational row, and it keeps the two things hand-rolled serialization throws away: LINQ translation into the document and change tracking with partial updates.

Map the payload as owned types, query it like any navigation, and when a document property becomes hot, index it through a computed column (SQL Server) or an expression/GIN index (PostgreSQL).

The discipline is in the boundary. JSON columns are for row-scoped, shape-flexible data. The moment something needs a foreign key, independent querying at scale, or schema enforcement, it has outgrown the document and earned its table.

By default, EF Core stores your OrderStatus enum as an int. Everything works, until a teammate alphabetizes the enum members, or inserts a new one in the middle, and every historical row silently means something else.

No error, no migration warning. Shipped becomes Cancelled in place.

Storing enums as strings removes that failure mode, but it is not free: it changes storage size, index behavior, and, the part almost nobody expects, how ORDER BY and comparisons translate to SQL. On PostgreSQL there is a third option that gets you most of both. Let's walk through all three.

Option 1: Ints (the Default)

With no configuration, an enum property maps to the provider's integer type:

public enum OrderStatus
{
    Draft = 0,
    Submitted = 1,
    Shipped = 2,
    Cancelled = 3
}

public class Order
{
    public Guid Id { get; set; }
    public OrderStatus Status { get; set; }
}

Pros:

• 4 bytes per value, cheap to index and compare.
• OrderBy(o => o.Status) sorts in numeric declaration order, which often matches workflow order.

Cons:

• The mapping lives only in your C# source. The database has 2, and nothing stops an unrelated 2 from arriving via raw SQL.
• Reordering or inserting members renumbers everything after the change. This is the silent data corruption scenario.
• Every debugging session involves a mental lookup table, and every report writer needs a copy of your enum.

If you keep ints, make the numbering explicit and append-only, exactly like the example above. Never rely on implicit values, and treat the numbers as a public contract.

Option 2: Strings

One line converts storage to the member name:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.Property(o => o.Status)
            .HasConversion<string>()
            .HasMaxLength(50);
    }
}

Or model-wide, so no enum ever slips through as an int, using the approach from custom model conventions:

protected override void ConfigureConventions(
    ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<Enum>()
        .HaveConversion<string>()
        .HaveMaxLength(50);
}

Always set the max length. Without it you get nvarchar(max) or text, which is wasteful and, on SQL Server, hostile to indexing.

What you gain:

• Reorder-proof. The stored value is 'Shipped'. Renumbering the C# enum changes nothing in the database.
• Self-describing data. Queries in psql or SSMS, log output, and reports all read naturally.

What you pay, and this is the part that surprises people:

• Comparisons translate to string comparisons. Where(o => o.Status > OrderStatus.Submitted) becomes WHERE Status > 'Submitted', an alphabetical comparison that has nothing to do with your workflow. EF Core translates the operator faithfully; the semantics changed underneath it.
• ORDER BY is alphabetical. Cancelled, Draft, Shipped, Submitted. If a UI sorts by status, you now need an explicit ranking, either a switch expression translated in the query or a lookup table.
• Storage and index size grow. 'Submitted' is 9 characters versus 4 bytes. On a 100-million-row table with an index on status, that is real space, though compression usually blunts it.

The comparison change is worth internalizing: after the conversion, only == and != mean what they meant before. Range checks and sorting need redesign. This is a general property of value conversions, the conversion applies to values, and operators run in the store type.

A rename is also no longer free. Rename Submitted to Placed in C# and every existing 'Submitted' row fails to materialize. Ship the rename together with a data migration:

UPDATE "Orders" SET "Status" = 'Placed' WHERE "Status" = 'Submitted';

Option 3: Native PostgreSQL Enums

PostgreSQL has first-class enum types, and Npgsql maps CLR enums onto them. You get compact storage (4 bytes), readable query output, database-side validation of allowed values, and sorting by the enum's declared order.

Register the enum in two places, the data source and the model:

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.MapEnum<OrderStatus>();
var dataSource = dataSourceBuilder.Build();

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(dataSource, npgsql => npgsql.MapEnum<OrderStatus>()));

Since Npgsql 9, MapEnum inside UseNpgsql also registers the type with the model, and the migration creates it:

CREATE TYPE order_status AS ENUM ('draft', 'submitted', 'shipped', 'cancelled');

The catch is schema evolution. Adding a value is easy (ALTER TYPE order_status ADD VALUE 'refunded'), but it cannot run inside a transaction on older Postgres versions, which can complicate migration tooling. Removing or renaming a value means creating a new type and rewriting the column. Native enums are the right call for genuinely stable sets, and a poor one for anything still churning.

If you are already on Postgres for other reasons (I made the broader case in PostgreSQL vs SQL Server for .NET developers), native enums are worth a look for your most stable, most queried status columns.

Which One Should You Pick?

• Default: strings with a max length, applied as a model-wide convention. Business apps refactor enums far more often than they hit enum-column storage limits, and self-describing data pays for itself in every incident investigation.
• Ints when the table is huge, the enum is stable and explicitly numbered, and the column is heavily indexed. Also when range semantics (>=) genuinely map to the numeric order and you want them translated.
• Native Postgres enums for stable vocabularies on Postgres-committed teams: order status in a mature domain, ISO-like code sets, severity levels.

Whatever you choose, be careful with [Flags] enums in mapped properties. String conversion stores combinations as comma-separated names like 'Draft, Submitted', which are painful to query, and native Postgres enums cannot represent combinations at all. If you must persist flags, keep the int mapping, or model the flags as separate boolean columns or a JSON column instead.

Summary

The default int mapping is a refactoring landmine: reorder the enum and the data silently changes meaning. HasConversion<string>(), ideally as a model-wide convention, defuses it, but remember what you traded away: comparisons and ORDER BY now operate on names, not on your declaration order, so only equality survives the conversion unchanged.

On PostgreSQL, native enum types recover compact storage, declared-order sorting, and database-side validation, at the cost of heavier schema evolution.

Pick per column, but pick consciously. The worst outcome is the accidental one: an implicit int mapping nobody chose, waiting for the first well-intentioned cleanup of the enum file.

Every EF Core tutorial shows entities with a single Id property. Then you model a join table or a child entity that has no natural single-column identity, and suddenly you need a composite key.

The configuration is one line. The behavior changes it drags in are not. Find takes multiple arguments in a specific order, relationships need multi-column foreign keys, and the order of key columns silently decides what your primary key index can do.

Here is how composite keys actually behave in EF Core, and when you should skip them for a surrogate key.

Configuring a Composite Key

Composite keys cannot be configured with the [Key] attribute on individual properties. You need either the Fluent API or the [PrimaryKey] attribute (EF Core 7+).

Here is the classic example, an order line that is identified by the order and the product:

public class OrderItem
{
    public Guid OrderId { get; set; }
    public Guid ProductId { get; set; }
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }

    public Order Order { get; set; } = null!;
    public Product Product { get; set; } = null!;
}

The Fluent API configuration:

public class OrderItemConfiguration : IEntityTypeConfiguration<OrderItem>
{
    public void Configure(EntityTypeBuilder<OrderItem> builder)
    {
        builder.HasKey(oi => new { oi.OrderId, oi.ProductId });
    }
}

Or with the attribute, where the order of names matters just as much:

[PrimaryKey(nameof(OrderId), nameof(ProductId))]
public class OrderItem
{
    // ...
}

The order you declare the columns in is the order of the primary key index. (OrderId, ProductId) means the database can seek efficiently on OrderId alone, but a query filtering only on ProductId scans. Put the column you filter by most often first. I covered how index column order affects query plans in PostgreSQL indexes for .NET developers.

How Find Changes

FindAsync is built around primary keys, so with a composite key it takes multiple values:

var item = await context.OrderItems.FindAsync(orderId, productId);

Two things to watch:

• The values must be passed in the declaration order from HasKey. Swap them and you get a runtime failure or a silent miss, and the compiler cannot help you because both are Guid.
• FindAsync checks the change tracker before querying the database, same as with single keys. That is usually a free cache hit, but it can return stale data in long-lived contexts.

I dig into that behavior in Find vs FirstOrDefault in EF Core.

If the argument order makes you nervous, a FirstOrDefaultAsync with named predicates is more explicit:

var item = await context.OrderItems
    .FirstOrDefaultAsync(oi => oi.OrderId == orderId && oi.ProductId == productId);

Relationships Against a Composite Key

Once an entity has a composite key, any entity referencing it needs a composite foreign key with matching column types and order.

public class Shipment
{
    public Guid Id { get; set; }
    public Guid OrderId { get; set; }
    public Guid ProductId { get; set; }

    public OrderItem OrderItem { get; set; } = null!;
}

public class ShipmentConfiguration : IEntityTypeConfiguration<Shipment>
{
    public void Configure(EntityTypeBuilder<Shipment> builder)
    {
        builder.HasOne(s => s.OrderItem)
            .WithMany()
            .HasForeignKey(s => new { s.OrderId, s.ProductId });
    }
}

This is where composite keys start to spread. Every referencing table carries both columns, every join condition has two predicates, and every new relationship is a chance to get the column order wrong. EF Core validates the shapes at model building time, which helps, but the extra ceremony is real. The patterns for configuring these correctly are the same ones I covered in entity relationships in EF Core.

No Value Generation

Single-column integer keys get identity values from the database. Composite keys get nothing. You must set every key component yourself before SaveChanges, or the insert fails.

That is fine for join tables where both values are existing foreign keys. It is painful for anything else, because you have just signed up for client-side key management. If you find yourself inventing one of the key parts (a sequence number, a timestamp), that is a strong sign you want a surrogate key instead, or database-generated ids like the ones I compared in identity vs sequence vs HiLo key generation.

Composite Keys in Many-to-Many Join Entities

The most legitimate home for a composite key is an explicit join entity. EF Core creates exactly this shape when you let it scaffold a skip navigation, and you can take control of it when the join table carries payload:

public class StudentCourse
{
    public Guid StudentId { get; set; }
    public Guid CourseId { get; set; }
    public DateTime EnrolledAtUtc { get; set; }
    public decimal? Grade { get; set; }
}

modelBuilder.Entity<Student>()
    .HasMany(s => s.Courses)
    .WithMany(c => c.Students)
    .UsingEntity<StudentCourse>(
        j => j.HasOne<Course>().WithMany().HasForeignKey(sc => sc.CourseId),
        j => j.HasOne<Student>().WithMany().HasForeignKey(sc => sc.StudentId),
        j => j.HasKey(sc => new { sc.StudentId, sc.CourseId }));

Here the composite key is doing double duty: it is the identity and a uniqueness constraint that prevents duplicate enrollments. No surrogate key can give you the second part for free.

When Does a Surrogate Key Win?

My rule of thumb after years of maintaining both:

• Composite key: join tables, child tables always accessed through the parent, tables nothing else references.
• Surrogate key plus unique index: everything else.

The surrogate-plus-unique-index pattern gives you the same duplicate protection without the downsides:

// OrderItem gains a surrogate key property:
// public Guid Id { get; set; }

builder.HasKey(oi => oi.Id);

builder.HasIndex(oi => new { oi.OrderId, oi.ProductId })
    .IsUnique();

Reasons the surrogate wins more often than you would expect:

• Referencing gets simpler. Foreign keys are one column, joins are one predicate, and no downstream table repeats your key structure.
• The key never changes. Natural keys have a habit of becoming not-so-natural. A product merge or an order renumbering with a composite natural key is a multi-table migration you do not want to write.
• APIs and URLs stay clean. /order-items/{id} beats encoding two guids into a route.
• Tooling assumes single keys. Generic repositories, FindAsync wrappers, and audit patterns all get uglier with composite keys.

The cost is one extra column and one extra index. For a high-volume join table with no inbound references, that cost buys you nothing, which is why join tables stay composite.

Summary

Composite keys in EF Core are a one-line configuration with a long tail of consequences. HasKey with an anonymous type (or [PrimaryKey]) defines them, FindAsync needs values in declaration order, relationships need matching multi-column foreign keys, and value generation is off the table entirely.

Use them where they model reality: join entities and parent-scoped children where the pair of foreign keys is the identity, and the key doubles as a uniqueness constraint. For anything that other tables reference or that surfaces in an API, a surrogate key with a unique index gives you the same guarantees with far less friction.

Column order is the detail people miss. Whether it is the primary key or the backing unique index, lead with the column you filter by most.

What Are Value Conversions?

EF Core value conversions let you transform a property's value when it's stored in the database and when it's read back into your entity. You define a pair of expressions: one for writing and one for reading. EF Core applies them transparently.

This is useful when your domain model uses types that don't map directly to database columns - enums, strongly typed IDs, value objects, or custom types.

HasConversion Basics

The simplest way to configure a value conversion is with HasConversion in your entity configuration:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.Property(o => o.Status)
            .HasConversion(
                status => status.ToString(),        // Write: enum → string
                value => Enum.Parse<OrderStatus>(value)); // Read: string → enum
    }
}

The first lambda converts the .NET value to the database value. The second converts it back. EF Core calls these automatically during SaveChangesAsync and queries.

Enum-to-String Conversions

Storing enums as strings is one of the most common use cases. It makes your database more readable and avoids breaking changes when you reorder enum members.

EF Core provides a built-in converter for this:

builder.Property(o => o.Status)
    .HasConversion(new EnumToStringConverter<OrderStatus>())
    .HasMaxLength(50);

Without this, EF Core stores enums as integers by default. That works, but you end up with 0, 1, 2 in your database instead of Draft, Confirmed, Shipped.

Built-in Converters

EF Core ships with several built-in converters in the Microsoft.EntityFrameworkCore.Storage.ValueConversion namespace:

• BoolToStringConverter - stores a bool as configurable strings like "Y"/"N"
• BoolToZeroOneConverter - stores a bool as 0 or 1
• DateTimeToTicksConverter - stores a DateTime as a long tick count
• EnumToStringConverter<TEnum> - stores an enum as its member name
• EnumToNumberConverter<TEnum, TNumber> - stores an enum as a numeric type of your choice
• GuidToStringConverter - stores a Guid as a string
• TimeSpanToTicksConverter - stores a TimeSpan as a long tick count

You can use any of these directly with HasConversion:

builder.Property(o => o.IsActive)
    .HasConversion(new BoolToStringConverter("No", "Yes"));

Custom Converters

For more complex scenarios, create a custom ValueConverter<TModel, TProvider>:

public sealed record Email(string Value);

public class EmailConverter : ValueConverter<Email, string>
{
    public EmailConverter()
        : base(
            email => email.Value,
            value => new Email(value))
    {
    }
}

Then apply it:

builder.Property(u => u.Email)
    .HasConversion(new EmailConverter())
    .HasMaxLength(255);

For value objects with a single property, this is the cleanest approach. You keep your domain model expressive without polluting the database schema.

Strongly Typed IDs

Strongly typed IDs prevent you from accidentally passing an OrderId where a CustomerId is expected. Value conversions make them work with EF Core:

public readonly record struct OrderId(Guid Value);

public class OrderIdConverter : ValueConverter<OrderId, Guid>
{
    public OrderIdConverter()
        : base(
            id => id.Value,
            value => new OrderId(value))
    {
    }
}

Configure in your DbContext:

builder.Property(o => o.Id)
    .HasConversion(new OrderIdConverter());

Or apply it globally using conventions (EF Core 6+):

protected override void ConfigureConventions(
    ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<OrderId>()
        .HaveConversion<OrderIdConverter>();
}

Value Comparers

EF Core uses value comparers to determine if a property's value has changed. For reference types, the default comparer uses ReferenceEquals, which means the change tracker might not detect changes to mutable objects.

You need a custom ValueComparer when your converted type is a class:

builder.Property(o => o.Tags)
    .HasConversion(
        tags => string.Join(',', tags),
        value => value.Split(',', StringSplitOptions.RemoveEmptyEntries).ToList())
    .Metadata.SetValueComparer(
        new ValueComparer<List<string>>(
            (a, b) => a.SequenceEqual(b),
            c => c.Aggregate(0, (h, v) => HashCode.Combine(h, v.GetHashCode())),
            c => c.ToList()));

The three expressions define equality, hash code, and snapshot. Without a proper comparer, EF Core either misses changes or generates unnecessary updates.

JSON Columns

EF Core supports mapping object graphs to JSON columns through owned types and, in EF Core 10, complex types. This is model-level JSON mapping rather than a value converter, so nested members remain available to translated queries:

builder.OwnsOne(o => o.ShippingAddress, address =>
{
    address.ToJson();
});

For simpler cases, you can use a manual JSON conversion:

builder.Property(o => o.Metadata)
    .HasConversion(
        meta => JsonSerializer.Serialize(meta, JsonSerializerOptions.Default),
        json => JsonSerializer.Deserialize<OrderMetadata>(
            json, JsonSerializerOptions.Default)!)
    .HasColumnType("jsonb");

The converter approach is fine for blobs of semi-structured data, but the serialized string is opaque to EF Core. It cannot translate queries against individual properties, which is exactly what the model-level JSON mapping above gives you.

Limitations

Value conversions have a few important constraints:

• Null handling: Null values are never passed through the converter. EF Core handles nulls separately. A nullable property stores NULL in the database without invoking the converter.
• Navigations: Converters apply to scalar properties, never to navigation properties or entity collections. Use owned types or JSON columns for those. A primitive collection like List<string> can be converted (as the tags example above shows), but then it needs a value comparer.
• Querying: the database only sees the converted value. Filtering on equality works because EF Core converts your parameters too, but operations that need the original type's semantics don't. Where(o => o.Status > OrderStatus.Confirmed) on a string-stored enum compares alphabetically, not by enum order.
• Sorting: same problem. OrderBy(o => o.Status) sorts by the stored string, so Cancelled comes before Draft.

For value objects with multiple properties, a value converter to a single column doesn't fit. Use complex types (EF Core 8+) or owned entities so each property gets its own column.

Applying Conversions Globally

Instead of configuring each property individually, use ConfigureConventions to apply conversions across all entities:

protected override void ConfigureConventions(
    ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<DateTime>()
        .HaveConversion<DateTimeToUtcConverter>();

    configurationBuilder.Properties<OrderStatus>()
        .HaveConversion<EnumToStringConverter<OrderStatus>>()
        .HaveMaxLength(50);
}

DateTimeToUtcConverter is a small custom converter that normalizes every DateTime to UTC:

public class DateTimeToUtcConverter : ValueConverter<DateTime, DateTime>
{
    public DateTimeToUtcConverter()
        : base(
            value => value.ToUniversalTime(),
            value => DateTime.SpecifyKind(value, DateTimeKind.Utc))
    {
    }
}

This keeps your entity configurations clean and ensures consistency across the entire model.

Summary

Use HasConversion when a domain value has a stable scalar representation in the database. Add a value comparer for mutable reference types so the change tracker can snapshot and compare them correctly. Apply repeated conversions through ConfigureConventions, and use provider JSON mapping rather than a converter when nested members must remain queryable.

Object inheritance has no single natural relational representation. TPH, TPT, and TPC distribute columns and joins differently, so the choice affects query shape long after the mapping code is written. Decide from the reads you need and the constraints you value, then verify the generated SQL.

Inheritance Mapping in EF Core

When your domain model uses inheritance - a base Payment class with CreditCardPayment and BankTransferPayment subclasses - EF Core needs a strategy to map this to relational tables. The two main approaches are Table Per Hierarchy (TPH) and Table Per Type (TPT).

The wrong strategy becomes expensive to change once the hierarchy contains production data. The choice affects query performance, schema complexity, and which constraints the database can express.

Table Per Hierarchy (TPH)

TPH stores all types in a single table with a discriminator column that indicates the type:

public abstract class Payment
{
    public Guid Id { get; set; }
    public decimal Amount { get; set; }
    public DateTime CreatedAt { get; set; }
    public string Currency { get; set; } = "USD";
}

public class CreditCardPayment : Payment
{
    public string CardNumber { get; set; } = string.Empty;
    public string CardHolderName { get; set; } = string.Empty;
    public string ExpiryDate { get; set; } = string.Empty;
}

public class BankTransferPayment : Payment
{
    public string BankName { get; set; } = string.Empty;
    public string AccountNumber { get; set; } = string.Empty;
    public string RoutingNumber { get; set; } = string.Empty;
}

public class CryptoPayment : Payment
{
    public string WalletAddress { get; set; } = string.Empty;
    public string Network { get; set; } = string.Empty;
}

TPH is the default in EF Core. One Payments table stores everything:

• A credit card payment row fills Amount, Currency, Discriminator = 'CreditCard', CardNumber, and CardHolderName, while BankName, AccountNumber, and WalletAddress are NULL.
• A bank transfer row fills Amount, Currency, Discriminator = 'BankTransfer', BankName, and AccountNumber, while all the credit card and crypto columns are NULL.

Every subclass-specific column exists on every row, and rows of other types leave them NULL.

Configure the discriminator:

public class PaymentConfiguration : IEntityTypeConfiguration<Payment>
{
    public void Configure(EntityTypeBuilder<Payment> builder)
    {
        builder.ToTable("Payments");

        builder.HasDiscriminator<string>("PaymentType")
            .HasValue<CreditCardPayment>("CreditCard")
            .HasValue<BankTransferPayment>("BankTransfer")
            .HasValue<CryptoPayment>("Crypto");

        builder.Property("PaymentType")
            .HasMaxLength(50);
    }
}

Table Per Type (TPT)

TPT uses a separate table for each type. The base class gets one table, each subclass gets another table with a foreign key back to the base:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Payment>().ToTable("Payments");
    modelBuilder.Entity<CreditCardPayment>().ToTable("CreditCardPayments");
    modelBuilder.Entity<BankTransferPayment>().ToTable("BankTransferPayments");
    modelBuilder.Entity<CryptoPayment>().ToTable("CryptoPayments");
}

On EF Core 7+, you can also state the intent explicitly with modelBuilder.Entity<Payment>().UseTptMappingStrategy();, but the per-type ToTable calls alone are enough to trigger TPT.

This creates four tables:

• Payments (Id, Amount, Currency, CreatedAt)
• CreditCardPayments (Id → FK to Payments, CardNumber, CardHolderName, ExpiryDate)
• BankTransferPayments (Id → FK to Payments, BankName, AccountNumber, RoutingNumber)
• CryptoPayments (Id → FK to Payments, WalletAddress, Network)

Performance Comparison

This is where the two strategies diverge significantly.

Querying all payments (TPH):

SELECT * FROM Payments

One table scan. Fast.

Querying all payments (TPT):

SELECT p.*, cc.*, bt.*, cr.*
FROM Payments p
LEFT JOIN CreditCardPayments cc ON p.Id = cc.Id
LEFT JOIN BankTransferPayments bt ON p.Id = bt.Id
LEFT JOIN CryptoPayments cr ON p.Id = cr.Id

Multiple LEFT JOINs. Gets slower with each type added.

Querying a specific type (TPH):

var creditCardPayments = await dbContext.Set<CreditCardPayment>()
    .Where(p => p.Amount > 100)
    .ToListAsync();

SELECT * FROM Payments WHERE PaymentType = 'CreditCard' AND Amount > 100

Fast - just a filter on the discriminator column.

Querying a specific type (TPT):

SELECT p.*, cc.*
FROM Payments p
INNER JOIN CreditCardPayments cc ON p.Id = cc.Id
WHERE p.Amount > 100

Still needs a JOIN, but only one.

Inserting Data

TPH: Single INSERT to one table.

dbContext.Set<CreditCardPayment>().Add(new CreditCardPayment
{
    Amount = 100,
    Currency = "USD",
    CardNumber = "4111111111111111",
    CardHolderName = "John Doe",
    ExpiryDate = "12/28"
});
await dbContext.SaveChangesAsync();

TPT: Two INSERTs - one to the base table, one to the subclass table (in a transaction).

The INSERT overhead matters at high write volumes. TPH is consistently better for writes.

Data Integrity

TPH disadvantage: Subclass-specific columns must be nullable. You can't enforce that CardNumber is required at the database level because BankTransferPayment rows don't have it. You need application-level validation.

TPT advantage: Each subclass table can enforce its own NOT NULL constraints. CreditCardPayments.CardNumber can be NOT NULL.

// TPT allows proper constraints
modelBuilder.Entity<CreditCardPayment>(b =>
{
    b.Property(p => p.CardNumber).IsRequired().HasMaxLength(19);
    b.Property(p => p.CardHolderName).IsRequired().HasMaxLength(100);
});

Table Per Concrete Type (TPC)

EF Core 7 introduced TPC as a third option. Each concrete type gets its own table with all columns - no foreign keys between them:

modelBuilder.Entity<Payment>().UseTpcMappingStrategy();
modelBuilder.Entity<CreditCardPayment>().ToTable("CreditCardPayments");
modelBuilder.Entity<BankTransferPayment>().ToTable("BankTransferPayments");
modelBuilder.Entity<CryptoPayment>().ToTable("CryptoPayments");

TPC queries use UNION ALL instead of JOINs:

SELECT * FROM CreditCardPayments
UNION ALL
SELECT * FROM BankTransferPayments
UNION ALL
SELECT * FROM CryptoPayments

TPC is good when you rarely query across all types and mostly query specific subtypes.

One caveat: TPC works best with client-generated keys like Guid. A plain identity column cannot guarantee uniqueness across separate tables, so EF Core generates integer keys from a single shared sequence instead.

Side-by-Side Comparison

Here's how the three strategies compare across the factors that matter:

Which Strategy Should You Choose?

My recommendation: Start with TPH unless you have a strong reason not to. The performance advantage is significant, and the nullable column issue is manageable with proper validation.

Use TPT when:

• You have many subclass-specific columns and most would be NULL in TPH
• Database-level constraints on subclass properties are critical
• You rarely query across all types

Use TPC when:

• Each concrete type is mostly queried independently
• You need strong constraints without JOINs

Querying Gotchas Worth Knowing

A few things that surprise people in production:

OfType<T>() translates to a discriminator filter with TPH, so this stays a single-table query:

var cardPayments = await dbContext.Payments
    .OfType<CreditCardPayment>()
    .Where(p => p.Amount > 100)
    .ToListAsync();

Global query filters apply to the whole hierarchy. You can only define a query filter on the root type, and it applies to every subclass. You can't filter just one payment type globally.

The discriminator column has no index by default. If you frequently query a rare subtype in a huge table, add an index on the discriminator (or a filtered index for that discriminator value). This is the same class of problem as any other query performance mistake: measure first, then index.

Switching Strategies Later

Changing the mapping strategy is a schema migration:

// To switch from TPH to TPT:
modelBuilder.Entity<CreditCardPayment>().ToTable("CreditCardPayments");
modelBuilder.Entity<BankTransferPayment>().ToTable("BankTransferPayments");

// dotnet ef migrations add SwitchToTpt

Here's the critical part: the generated migration only changes the schema. It creates the new subclass tables and drops the subclass columns from the old table, but it does not copy your existing data across.

On a production table, you need to add custom SQL to the migration that moves the data before the old columns are dropped. Follow the usual migration best practices: review the generated migration, add the data-copy step, and test it against a restored production backup first.

Summary

TPH is the simplest starting point and usually gives polymorphic queries the least join overhead. TPT trades additional joins for normalized subclass tables, while TPC duplicates base columns to keep concrete-type reads independent. Choose from the actual query mix and required database constraints, then benchmark the generated SQL before the schema becomes expensive to change.

The tradeoff: query and update access is less obvious unless the convention is consistent.

What Are Shadow Properties?

Shadow properties are properties that exist in the EF Core model - mapped to database columns - but don't exist as CLR properties on your entity class. They're tracked by the change tracker and included in queries, but your domain model doesn't know about them.

This keeps your entity classes clean. Infrastructure concerns like CreatedAt, UpdatedAt, or hidden foreign keys stay in the EF Core configuration layer where they belong.

Defining Shadow Properties

Define a shadow property in your entity configuration:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.Property<DateTime>("CreatedAt");
        builder.Property<DateTime>("UpdatedAt");
        builder.Property<string>("CreatedBy").HasMaxLength(100);
    }
}

These properties don't exist on the Order class, but EF Core creates the corresponding database columns:

CREATE TABLE "Orders" (
    "Id" uuid NOT NULL,
    "Status" varchar(50) NOT NULL,
    "CreatedAt" timestamptz NOT NULL,
    "UpdatedAt" timestamptz NOT NULL,
    "CreatedBy" varchar(100),
    CONSTRAINT "PK_Orders" PRIMARY KEY ("Id")
);

Note that CreatedBy is nullable. A shadow property with a reference type is optional unless you add IsRequired(), because there is no nullable reference type annotation to infer from.

Your Order entity stays focused on domain logic without audit infrastructure leaking in.

When to Use Shadow Properties

Shadow properties are most useful for:

• Audit fields - CreatedAt, UpdatedAt, CreatedBy that every entity needs but aren't part of the domain
• Foreign keys - EF Core automatically creates shadow foreign keys for navigation properties
• Soft delete flags - IsDeleted columns used by query filters but hidden from the entity
• Concurrency tokens - RowVersion or xmin columns for optimistic concurrency
• Tenant IDs - multi-tenancy discriminators that don't belong in the domain model

Automatic Shadow Properties

EF Core creates shadow properties automatically for foreign keys when you define a navigation property without a corresponding foreign key property:

public class Order
{
    public Guid Id { get; set; }
    public Customer Customer { get; set; } // Navigation property
    // No CustomerId property defined
}

EF Core creates a shadow property named CustomerId of type Guid. You can see this in your migrations:

"CustomerId" uuid NOT NULL

You can configure the shadow foreign key explicitly:

builder.HasOne(o => o.Customer)
    .WithMany(c => c.Orders)
    .HasForeignKey("CustomerId");

Accessing Shadow Properties

Since shadow properties don't exist on the entity, you use EF.Property<T>() to access them in LINQ queries:

var recentOrders = await context.Orders
    .OrderByDescending(o => EF.Property<DateTime>(o, "CreatedAt"))
    .Take(10)
    .ToListAsync();

var ordersCreatedToday = await context.Orders
    .Where(o => EF.Property<DateTime>(o, "CreatedAt") >= DateTime.UtcNow.Date)
    .ToListAsync();

For reading or writing shadow properties on a specific entity, use the change tracker:

var entry = context.Entry(order);

// Read
var createdAt = entry.Property<DateTime>("CreatedAt").CurrentValue;

// Write
entry.Property<DateTime>("UpdatedAt").CurrentValue = DateTime.UtcNow;

Audit Fields With Shadow Properties

A common pattern is setting audit shadow properties automatically in SaveChangesAsync. This is where shadow properties really shine:

public class AppDbContext : DbContext
{
    public override async Task<int> SaveChangesAsync(
        CancellationToken ct = default)
    {
        var now = DateTime.UtcNow;

        foreach (var entry in ChangeTracker.Entries())
        {
            if (entry.Metadata.FindProperty("CreatedAt") is null)
            {
                continue;
            }

            if (entry.State == EntityState.Added)
            {
                entry.Property("CreatedAt").CurrentValue = now;
                entry.Property("UpdatedAt").CurrentValue = now;
            }

            if (entry.State == EntityState.Modified)
            {
                entry.Property("UpdatedAt").CurrentValue = now;
            }
        }

        return await base.SaveChangesAsync(ct);
    }
}

Every entity gets CreatedAt and UpdatedAt without any of them knowing those fields exist. You could also use an EF Core interceptor for this.

Applying Shadow Properties to All Entities

Instead of configuring shadow properties on each entity individually, apply them in OnModelCreating:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    foreach (var entityType in modelBuilder.Model.GetEntityTypes())
    {
        if (entityType.IsOwned())
        {
            continue;
        }

        modelBuilder.Entity(entityType.ClrType)
            .Property<DateTime>("CreatedAt")
            .HasDefaultValueSql("now()");

        modelBuilder.Entity(entityType.ClrType)
            .Property<DateTime>("UpdatedAt")
            .HasDefaultValueSql("now()");
    }
}

This ensures consistency across all entities. I skip owned types because they're stored as part of their parent entity.

Shadow Properties With Query Filters

Shadow properties work well with global query filters for multi-tenancy or soft delete:

// Define shadow property
builder.Property<bool>("IsDeleted").HasDefaultValue(false);

// Apply query filter
builder.HasQueryFilter(o => !EF.Property<bool>(o, "IsDeleted"));

Now deleted entities are filtered out of all queries automatically, and the IsDeleted flag isn't part of your domain model.

For soft delete, intercept the delete operation:

foreach (var entry in ChangeTracker.Entries())
{
    if (entry.State == EntityState.Deleted &&
        entry.Metadata.FindProperty("IsDeleted") is not null)
    {
        entry.State = EntityState.Modified;
        entry.Property("IsDeleted").CurrentValue = true;
    }
}

Indexing Shadow Properties

You can create indexes on shadow properties for query performance:

builder.HasIndex("CreatedAt");
builder.HasIndex("IsDeleted");

// Composite index
builder.HasIndex("IsDeleted", "CreatedAt");

Shadow Properties vs Regular Properties

When should you use a shadow property instead of a regular property?

• Audit timestamps: shadow property, unless your domain logic actually reads CreatedAt (for example, to enforce a cancellation window).
• Foreign keys: shadow by default. Promote to a regular property if you filter or join by the FK often - EF.Property<Guid>(o, "CustomerId") everywhere gets old fast.
• Soft delete flags: shadow property, unless the domain has behavior attached to deletion (restore workflows, "deleted by" rules).
• Concurrency tokens: shadow property, unless domain logic compares versions explicitly.
• Domain-meaningful data: always a regular property. If the business talks about it, it belongs on the class.

The rule is simple: if the property is infrastructure or persistence-only, make it a shadow property. If the domain model needs it, make it a regular property.

There's a middle ground worth knowing: backing fields. If the domain needs the value internally but you don't want a public setter, map the column to a private field instead of using a shadow property.

Gotchas to Watch Out For

A few things that trip people up with shadow properties:

Detached entities lose shadow values. Shadow property values live in the change tracker, not on the object. If you serialize an entity, send it to a client, and re-attach it later, the shadow values are gone. EF Core will treat them as unset.

String-based access means no compiler safety. A typo in EF.Property<DateTime>(o, "CraetedAt") fails at runtime, not at compile time. Keep the property names in constants if you access them in more than one place.

They don't show up in projections automatically. If you need a shadow property value in a DTO, you must select it explicitly with EF.Property<T>() in the projection.

Summary

Shadow properties are useful for persistence metadata that should not become part of the domain API. Define them through one convention, use constants for string-based access, and project them explicitly when callers need the value. If the business gives a field meaning, make it a regular property instead of hiding it in the change tracker.

A value object belongs to an aggregate because of what it represents, not because it has its own database identity. Flattening it into the entity weakens the domain model, while giving it an artificial ID changes its semantics.

Why Value Objects Need Special Mapping

Value objects are a core DDD building block. They have no identity - two Money objects with the same amount and currency are equal. But EF Core needs to store them in a relational database.

You have three options:

1. Owned types - stored as columns in the parent table (EF Core 2.0+)
2. Complex types - similar but with stricter restrictions (EF Core 8+)
3. Value conversions - single-property value objects stored as one column

Owned types are the most flexible approach.

Basic Owned Type

Define the value object:

public sealed record Money
{
    public decimal Amount { get; init; }
    public string Currency { get; init; }

    private Money() { }

    public Money(decimal amount, string currency)
    {
        if (amount < 0)
            throw new ArgumentException("Amount cannot be negative.", nameof(amount));
        if (string.IsNullOrWhiteSpace(currency))
            throw new ArgumentException("Currency is required.", nameof(currency));

        Amount = amount;
        Currency = currency;
    }

    public static Money Zero(string currency) => new(0, currency);
}

Configure as owned:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.HasKey(x => x.Id);

        builder.OwnsOne(x => x.TotalAmount, money =>
        {
            money.Property(m => m.Amount)
                .HasColumnName("TotalAmount")
                .HasPrecision(18, 2);

            money.Property(m => m.Currency)
                .HasColumnName("TotalCurrency")
                .HasMaxLength(3);
        });
    }
}

This stores Money as two columns in the Orders table:

CREATE TABLE "Orders" (
    "Id" uuid NOT NULL,
    "TotalAmount" numeric(18,2) NOT NULL,
    "TotalCurrency" varchar(3) NOT NULL
);

No separate table. No separate ID. The value object lives inside its parent.

Address Value Object

A common example with multiple properties:

public sealed record Address
{
    public string Street { get; init; }
    public string City { get; init; }
    public string State { get; init; }
    public string ZipCode { get; init; }
    public string Country { get; init; }

    private Address() { }

    public Address(
        string street, string city, string state,
        string zipCode, string country)
    {
        Street = street;
        City = city;
        State = state;
        ZipCode = zipCode;
        Country = country;
    }
}

Configure:

builder.OwnsOne(x => x.ShippingAddress, address =>
{
    address.Property(a => a.Street)
        .HasColumnName("ShippingStreet")
        .HasMaxLength(200);

    address.Property(a => a.City)
        .HasColumnName("ShippingCity")
        .HasMaxLength(100);

    address.Property(a => a.State)
        .HasColumnName("ShippingState")
        .HasMaxLength(50);

    address.Property(a => a.ZipCode)
        .HasColumnName("ShippingZipCode")
        .HasMaxLength(20);

    address.Property(a => a.Country)
        .HasColumnName("ShippingCountry")
        .HasMaxLength(100);
});

Multiple Owned Types of the Same Type

An order might have both a shipping and billing address:

public class Order
{
    public Guid Id { get; private set; }
    public Address ShippingAddress { get; private set; }
    public Address BillingAddress { get; private set; }
}

Configure each one separately:

builder.OwnsOne(x => x.ShippingAddress, address =>
{
    address.Property(a => a.Street).HasColumnName("ShippingStreet");
    address.Property(a => a.City).HasColumnName("ShippingCity");
    // ...
});

builder.OwnsOne(x => x.BillingAddress, address =>
{
    address.Property(a => a.Street).HasColumnName("BillingStreet");
    address.Property(a => a.City).HasColumnName("BillingCity");
    // ...
});

Result:

CREATE TABLE "Orders" (
    "Id" uuid NOT NULL,
    "ShippingStreet" varchar(200),
    "ShippingCity" varchar(100),
    "BillingStreet" varchar(200),
    "BillingCity" varchar(100),
    -- ...
);

Owned Collections (Separate Table)

For collections of value objects, use OwnsMany:

public class Order
{
    public Guid Id { get; private set; }
    private readonly List<LineItem> _lineItems = [];
    public IReadOnlyCollection<LineItem> LineItems => _lineItems;
}

public sealed record LineItem
{
    public Guid ProductId { get; init; }
    public int Quantity { get; init; }
    public Money UnitPrice { get; init; }
}

builder.OwnsMany(x => x.LineItems, lineItem =>
{
    lineItem.ToTable("OrderLineItems");

    lineItem.WithOwner().HasForeignKey("OrderId");

    lineItem.Property(li => li.ProductId);
    lineItem.Property(li => li.Quantity);

    lineItem.OwnsOne(li => li.UnitPrice, money =>
    {
        money.Property(m => m.Amount)
            .HasColumnName("UnitPrice")
            .HasPrecision(18, 2);
        money.Property(m => m.Currency)
            .HasColumnName("Currency")
            .HasMaxLength(3);
    });
});

OwnsMany creates a separate table because you can't flatten a collection into columns.

Nullable Owned Types

With nullable reference types enabled, a non-nullable owned navigation is required by default (EF Core 6+). To make a value object optional, declare the property as nullable (Address?) or configure the navigation explicitly:

builder.OwnsOne(x => x.ShippingAddress, address =>
{
    address.Property(a => a.Street).HasColumnName("ShippingStreet");
    // ...
});

builder.Navigation(x => x.ShippingAddress).IsRequired(false);

When ShippingAddress is null, all its columns will be null in the database.

Querying Owned Types

Access owned types in LINQ queries:

// Filter by owned type property
var expensiveOrders = await _db.Orders
    .Where(o => o.TotalAmount.Amount > 1000)
    .ToListAsync();

// Project owned type properties
var orderSummaries = await _db.Orders
    .Select(o => new
    {
        o.Id,
        Total = o.TotalAmount.Amount,
        Currency = o.TotalAmount.Currency,
        City = o.ShippingAddress.City
    })
    .ToListAsync();

EF Core translates these to SQL column access - no joins needed.

Owned Types vs Complex Types vs Value Conversions

How the three approaches compare (as of EF Core 8):

• Multiple properties: owned types and complex types support them; value conversions handle a single property only
• Nullability: owned types and value conversions can be optional; EF Core 8 complex types cannot (EF Core 10 lifted this)
• Collections: only owned types support them, via OwnsMany
• Nesting: owned types and complex types can nest other value objects; conversions can't
• Table placement: owned types can move to a separate table; complex types always share the parent table
• Hidden key: owned types carry a shadow key under the hood; complex types have none

Use value conversions for single-property value objects like Email or PhoneNumber. Use owned types for multi-property value objects like Money or Address. Use complex types when you want the same behavior without shadow keys.

I walk through a complete aggregate persisted this way in value objects with EF Core.

One Gotcha: Owned Types Are Still Entities

Under the hood, EF Core treats an owned type as an entity with a hidden shadow key tied to its owner. That leaks in a few places:

• Two owned instances with identical values are not interchangeable to EF Core the way true value objects are - replacing one is an update to the owner's row
• OwnsMany rows are keyed by the owner plus a synthetic ID, so reordering a collection can generate more SQL than you expect
• Sharing the same value object instance between two owners throws, because an owned instance can only belong to one owner

None of these are blockers, but they explain the occasional surprising UPDATE statement in your logs.

Summary

Use OwnsOne or OwnsMany when a value cannot exist independently from its aggregate owner. Configure nullability, column names, and table placement explicitly so persistence details do not blur the value object's semantics. On EF Core 10, also consider complex types when you want value semantics without the hidden identity of an owned entity.

Why Fluent API Over Conventions?

An entity relationship in EF Core is a link between two entity types, made up of a foreign key on the dependent side, the navigation properties you use to traverse it, and a delete behavior.

EF Core can infer relationships from conventions, but Fluent API gives you explicit control. The IEntityTypeConfiguration<T> pattern keeps that configuration explicit and separated by entity:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("orders");
        builder.HasKey(o => o.Id);

        // Relationships defined here
    }
}

Register all configurations:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyConfigurationsFromAssembly(
        typeof(ApplicationDbContext).Assembly);
}

The relationships this article configures, and how they connect, look like this:

The same self-reference can represent an arbitrary tree; hierarchical data in EF Core covers recursive reads, deletes, and larger-tree alternatives.

One-to-Many

The most common relationship. An order has many line items:

public class Order
{
    public Guid Id { get; set; }
    public string CustomerName { get; set; }
    public DateTime CreatedAt { get; set; }
    public List<LineItem> LineItems { get; set; } = [];
}

public class LineItem
{
    public Guid Id { get; set; }
    public Guid OrderId { get; set; }      // FK
    public string ProductName { get; set; }
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }
    public Order Order { get; set; }        // Navigation
}

Configure with Fluent API:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.HasMany(o => o.LineItems)
            .WithOne(li => li.Order)
            .HasForeignKey(li => li.OrderId)
            .OnDelete(DeleteBehavior.Cascade);
    }
}

Cascade means deleting an order also deletes its line items. Be intentional about this - sometimes you want Restrict or SetNull instead.

Without Navigation on the Child

If you don't want a navigation property from LineItem back to Order:

public class LineItem
{
    public Guid Id { get; set; }
    public Guid OrderId { get; set; }  // FK only, no nav property
    public string ProductName { get; set; }
}

// Configuration
builder.HasMany(o => o.LineItems)
    .WithOne()
    .HasForeignKey(li => li.OrderId);

One-to-One

A user has one profile:

public class User
{
    public Guid Id { get; set; }
    public string Email { get; set; }
    public UserProfile? Profile { get; set; }
}

public class UserProfile
{
    public Guid Id { get; set; }
    public Guid UserId { get; set; }
    public string DisplayName { get; set; }
    public string? Bio { get; set; }
    public User User { get; set; }
}

public class UserConfiguration : IEntityTypeConfiguration<User>
{
    public void Configure(EntityTypeBuilder<User> builder)
    {
        builder.HasOne(u => u.Profile)
            .WithOne(p => p.User)
            .HasForeignKey<UserProfile>(p => p.UserId)
            .OnDelete(DeleteBehavior.Cascade);
    }
}

You must specify which side holds the foreign key with HasForeignKey<UserProfile>.

Many-to-Many

A student enrolls in many courses. A course has many students:

public class Student
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public List<Course> Courses { get; set; } = [];
}

public class Course
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public List<Student> Students { get; set; } = [];
}

EF Core 5+ creates the join table automatically:

builder.HasMany(s => s.Courses)
    .WithMany(c => c.Students)
    .UsingEntity(j => j.ToTable("student_courses"));

Many-to-Many With Payload

When the join table needs extra columns (like enrollment date):

public class Enrollment
{
    public Guid StudentId { get; set; }
    public Guid CourseId { get; set; }
    public DateTime EnrolledAt { get; set; }
    public Grade? Grade { get; set; }
    public Student Student { get; set; }
    public Course Course { get; set; }
}

public enum Grade
{
    A, B, C, D, F
}

public class EnrollmentConfiguration
    : IEntityTypeConfiguration<Enrollment>
{
    public void Configure(EntityTypeBuilder<Enrollment> builder)
    {
        builder.ToTable("enrollments");

        builder.HasKey(e => new { e.StudentId, e.CourseId });

        builder.HasOne(e => e.Student)
            .WithMany(s => s.Enrollments)
            .HasForeignKey(e => e.StudentId);

        builder.HasOne(e => e.Course)
            .WithMany(c => c.Enrollments)
            .HasForeignKey(e => e.CourseId);
    }
}

Now Student and Course reference Enrollment instead of each other directly:

public class Student
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public List<Enrollment> Enrollments { get; set; } = [];
}

Self-Referencing Relationship

An employee has a manager (who is also an employee):

public class Employee
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public Guid? ManagerId { get; set; }
    public Employee? Manager { get; set; }
    public List<Employee> DirectReports { get; set; } = [];
}

builder.HasOne(e => e.Manager)
    .WithMany(e => e.DirectReports)
    .HasForeignKey(e => e.ManagerId)
    .OnDelete(DeleteBehavior.Restrict);

Use Restrict here - you don't want cascading deletes up the org chart.

Owned Types (Value Objects)

For value objects, use owned types:

public class Order
{
    public Guid Id { get; set; }
    public Address ShippingAddress { get; set; }
    public Money TotalAmount { get; set; }
}

public class Address
{
    public string Street { get; set; }
    public string City { get; set; }
    public string ZipCode { get; set; }
    public string Country { get; set; }
}

public sealed record Money(decimal Amount, string Currency);

builder.OwnsOne(o => o.ShippingAddress, address =>
{
    address.Property(a => a.Street).HasColumnName("shipping_street");
    address.Property(a => a.City).HasColumnName("shipping_city");
    address.Property(a => a.ZipCode).HasColumnName("shipping_zip");
    address.Property(a => a.Country).HasColumnName("shipping_country");
});

builder.OwnsOne(o => o.TotalAmount, money =>
{
    money.Property(m => m.Amount).HasColumnName("total_amount");
    money.Property(m => m.Currency).HasColumnName("total_currency");
});

Owned types are stored in the same table as the parent entity - no joins needed. I cover them in depth (including collections and DDD usage) in owned types for DDD value objects.

Loading Related Data

Configuring a relationship is half the story; the other half is how you load it. Your options are eager loading with Include, explicit loading, and lazy loading - each with different query patterns and pitfalls. I compare them in lazy vs eager vs explicit loading.

One tip that belongs here: when you Include multiple collections, watch out for cartesian explosion, and reach for query splitting when result sets multiply.

Indexes

EF Core creates an index on foreign key columns by convention, so OrderId is already covered. Add indexes for the columns your queries filter and sort on:

builder.HasIndex(o => o.CreatedAt);
builder.HasIndex(o => o.CustomerName);

// Unique index
builder.HasIndex(u => u.Email).IsUnique();

// Composite index
builder.HasIndex(e => new { e.CourseId, e.EnrolledAt });

Delete Behaviors

• Cascade: deleting the parent also deletes its children
• Restrict: deleting a parent with children throws an exception
• SetNull: deleting the parent sets the FK to null on the children (requires a nullable FK)
• ClientSetNull: like SetNull, but only for children the context is currently tracking; untracked children cause a database FK violation
• NoAction: the database decides (engine-dependent)

The defaults are Cascade for required relationships and ClientSetNull for optional ones. Be explicit about what you want - especially in PostgreSQL and SQL Server, where accidental cascades on big tables hurt.

Summary

Use conventions for unambiguous relationships and Fluent API where the foreign key, principal side, or delete behavior needs to be explicit. Model a many-to-many join as an entity as soon as the relationship carries data of its own. Review the generated constraints and indexes because the relationship is not complete until the database enforces the same intent.

Value objects should be modeled by their value, not forced to pretend they have an identity. Here is how to configure, query, and update them, and what changed in EF Core 9 and 10.

What Are Complex Types?

Complex types model value objects, which are types defined by their properties rather than an identity. In the original EF Core 8 implementation, unlike owned types, complex types:

• Cannot be null
• Cannot have a primary key
• Cannot reference other entities (no navigation properties)
• Always live inside the parent entity's table

They map cleanly to the DDD concept of a value object.

Defining Complex Types

public sealed record Address(
    string Street,
    string City,
    string State,
    string ZipCode,
    string Country);

public sealed record Money(decimal Amount, string Currency);

public class Order
{
    public Guid Id { get; private set; }
    public Address ShippingAddress { get; set; } = null!;
    public Money TotalAmount { get; set; } = null!;
    public DateTime CreatedAt { get; private set; }
}

Configuration

Fluent API

modelBuilder.Entity<Order>(builder =>
{
    builder.HasKey(o => o.Id);

    builder.ComplexProperty(o => o.ShippingAddress, address =>
    {
        address.Property(a => a.Street)
            .HasColumnName("shipping_street")
            .HasMaxLength(200);

        address.Property(a => a.City)
            .HasColumnName("shipping_city")
            .HasMaxLength(100);

        address.Property(a => a.State)
            .HasColumnName("shipping_state")
            .HasMaxLength(100);

        address.Property(a => a.ZipCode)
            .HasColumnName("shipping_zip")
            .HasMaxLength(20);

        address.Property(a => a.Country)
            .HasColumnName("shipping_country")
            .HasMaxLength(100);
    });

    builder.ComplexProperty(o => o.TotalAmount, money =>
    {
        money.Property(m => m.Amount)
            .HasColumnName("total_amount")
            .HasPrecision(18, 2);

        money.Property(m => m.Currency)
            .HasColumnName("total_currency")
            .HasMaxLength(3);
    });
});

Generated Table

CREATE TABLE orders (
    id UUID PRIMARY KEY,
    shipping_street VARCHAR(200) NOT NULL,
    shipping_city VARCHAR(100) NOT NULL,
    shipping_state VARCHAR(100) NOT NULL,
    shipping_zip VARCHAR(20) NOT NULL,
    shipping_country VARCHAR(100) NOT NULL,
    total_amount DECIMAL(18,2) NOT NULL,
    total_currency VARCHAR(3) NOT NULL,
    created_at TIMESTAMP NOT NULL
);

The columns are NOT NULL because complex types cannot be null.

Nested Complex Types

Complex types can contain other complex types:

public sealed record Coordinates(double Latitude, double Longitude);

public sealed record Address(
    string Street,
    string City,
    string State,
    string ZipCode,
    string Country,
    Coordinates Location);

builder.ComplexProperty(o => o.ShippingAddress, address =>
{
    address.Property(a => a.Street).HasColumnName("shipping_street");
    address.Property(a => a.City).HasColumnName("shipping_city");
    // ...

    address.ComplexProperty(a => a.Location, location =>
    {
        location.Property(l => l.Latitude).HasColumnName("shipping_lat");
        location.Property(l => l.Longitude).HasColumnName("shipping_lng");
    });
});

All properties are still flattened into the same table.

Querying

You can filter by complex type properties just like regular columns:

// Find orders shipping to a specific city
var orders = await db.Orders
    .Where(o => o.ShippingAddress.City == "London")
    .ToListAsync();

// Find orders over a certain amount
var largeOrders = await db.Orders
    .Where(o => o.TotalAmount.Amount > 1000 &&
                o.TotalAmount.Currency == "USD")
    .ToListAsync();

EF Core translates this to standard SQL:

SELECT * FROM orders
WHERE shipping_city = 'London';

SELECT * FROM orders
WHERE total_amount > 1000 AND total_currency = 'USD';

Updating Complex Types

Replace the entire value object (the records here are immutable):

// ✅ Replace the whole value object
order.ShippingAddress = new Address(
    "456 Oak Ave",
    order.ShippingAddress.City,
    order.ShippingAddress.State,
    order.ShippingAddress.ZipCode,
    order.ShippingAddress.Country,
    order.ShippingAddress.Location);

await db.SaveChangesAsync();

With records, use the with expression:

order.ShippingAddress = order.ShippingAddress with { Street = "456 Oak Ave" };
await db.SaveChangesAsync();

EF Core detects which properties changed and only updates those columns.

Complex Types vs Owned Types

Here's how the two compare, feature by feature (in EF Core 8):

• Nullability: complex types can never be null; owned types can be optional
• Identity: complex types have no key at all; owned types carry a hidden shadow key
• Navigation properties: complex types can't reference entities; owned types can
• Separate table: complex types are always inlined into the parent table; owned types can move to their own table with ToTable()
• Collections: complex types don't support collections; owned types do via OwnsMany
• Version support: complex types need EF Core 8+; owned types have existed since EF Core 2.0
• Semantics: complex types are true value types; owned types are "entities pretending to be values"

I go deeper on the owned-type approach in value objects with EF Core.

When to Choose Complex Types

• You want value semantics with no identity or navigation
• You want the value flattened into the owner's table or, on EF Core 10, mapped to a JSON column
• You are on EF Core 8 or later and the version supports the nullability and collection shape you need

When to Choose Owned Types

• You need navigation properties to other entities
• You want to store the value in a separate table
• You need an owned collection mapped to its own table
• You are on EF Core 2-7

Multiple Entities With the Same Complex Type

public sealed record FullName(string First, string Last);

public class Customer
{
    public Guid Id { get; set; }
    public FullName Name { get; set; } = null!;
    public Address BillingAddress { get; set; } = null!;
}

public class Supplier
{
    public Guid Id { get; set; }
    public FullName ContactName { get; set; } = null!;
    public Address WarehouseAddress { get; set; } = null!;
}

Configure each independently:

modelBuilder.Entity<Customer>(builder =>
{
    builder.ComplexProperty(c => c.Name, name =>
    {
        name.Property(n => n.First).HasColumnName("first_name");
        name.Property(n => n.Last).HasColumnName("last_name");
    });
    builder.ComplexProperty(c => c.BillingAddress, addr =>
    {
        addr.Property(a => a.Street).HasColumnName("billing_street");
        addr.Property(a => a.City).HasColumnName("billing_city");
    });
});

modelBuilder.Entity<Supplier>(builder =>
{
    builder.ComplexProperty(s => s.ContactName, name =>
    {
        name.Property(n => n.First).HasColumnName("contact_first_name");
        name.Property(n => n.Last).HasColumnName("contact_last_name");
    });
    builder.ComplexProperty(s => s.WarehouseAddress, addr =>
    {
        addr.Property(a => a.Street).HasColumnName("warehouse_street");
        addr.Property(a => a.City).HasColumnName("warehouse_city");
    });
});

Limitations

Complex types in EF Core 8 have restrictions:

1. Cannot be null - use owned types if nullability is needed
2. No collections - use OwnsMany for lists of value objects
3. No lazy loading - they're always loaded with the parent
4. No separate table - always in the same table as the entity
5. Equality not used by EF Core - change detection is property-by-property, not structural equality

What Changed in EF Core 9 and 10

Complex types were a v1 feature in EF Core 8, and the team has been closing the gaps since:

• EF Core 10 added support for optional (nullable) complex properties when the complex type contains at least one required property
• EF Core 10 made complex types the primary mechanism for mapping to JSON columns, which previously required owned types with ToJson()
• Complex type collections are supported when mapped to JSON

If you're on .NET 10, the "use owned types because complex types can't do X" cases have mostly disappeared. Check the EF Core release notes for your exact version before designing around an EF Core 8 limitation.

Summary

Complex types express values with no identity or navigation and keep their members queryable through LINQ. EF Core 8 maps required values into the owner's table; EF Core 10 adds optional complex properties and JSON mapping that can contain collections. Use owned types when you need an entity relationship, a separate table, or support on an older EF Core version.

Reference data, development fixtures, and production bootstrap data have different lifecycles. Using one seeding mechanism for all three creates non-deterministic migrations or lets sample data leak into production.

Why Seed Data?

Seeding is inserting a known set of starting rows into the database so the application has the data it needs to run. Every application needs some initial data: lookup tables, default roles, configuration records, test data for development. Without a consistent seeding strategy, developers end up with manual SQL scripts scattered across the team or databases in unpredictable states.

EF Core provides built-in seeding through HasData, but that's just one option. The right strategy depends on what you're seeding and when.

HasData: Built-in Model Seeding

The HasData method in your entity configuration tells EF Core to include seed data in migrations:

public class OrderStatusConfiguration : IEntityTypeConfiguration<OrderStatus>
{
    public void Configure(EntityTypeBuilder<OrderStatus> builder)
    {
        builder.HasKey(x => x.Id);

        builder.Property(x => x.Name).HasMaxLength(50);

        builder.HasData(
            new OrderStatus { Id = 1, Name = "Draft" },
            new OrderStatus { Id = 2, Name = "Confirmed" },
            new OrderStatus { Id = 3, Name = "Shipped" },
            new OrderStatus { Id = 4, Name = "Delivered" },
            new OrderStatus { Id = 5, Name = "Cancelled" });
    }
}

When you create a migration, EF Core generates InsertData operations:

migrationBuilder.InsertData(
    table: "OrderStatuses",
    columns: new[] { "Id", "Name" },
    values: new object[,]
    {
        { 1, "Draft" },
        { 2, "Confirmed" },
        { 3, "Shipped" },
        { 4, "Delivered" },
        { 5, "Cancelled" }
    });

HasData Limitations

HasData has strict rules:

• Primary keys are required - you must specify the key value for every seeded entity. No auto-generated keys.
• No navigation properties - you can't set related entities directly. Use foreign key values instead.
• Tracked by migrations - any change to seed data generates a new migration.
• No access to services or configuration - the values are baked into the model, so you can't read from IConfiguration or hash a password with an injected service.

That last one bites people seeding an admin user: you can't call your password hasher from HasData. That's a job for custom seeding code.

For entity relationships, seed related entities separately:

builder.HasData(
    new Role { Id = 1, Name = "Admin" });

// In a separate configuration
permissionBuilder.HasData(
    new Permission { Id = 1, Name = "users.read", RoleId = 1 },
    new Permission { Id = 2, Name = "users.write", RoleId = 1 });

UseSeeding and UseAsyncSeeding (EF Core 9+)

EF Core 9 added a first-class hook for custom seed logic: UseSeeding and UseAsyncSeeding on the options builder.

builder.Services.AddDbContext<AppDbContext>(options =>
    options
        .UseNpgsql(connectionString)
        .UseAsyncSeeding(async (context, _, ct) =>
        {
            var hasRoles = await context.Set<Role>().AnyAsync(ct);
            if (hasRoles)
            {
                return;
            }

            context.Set<Role>().AddRange(
                new Role("Admin"),
                new Role("User"));

            await context.SaveChangesAsync(ct);
        }));

The seeding delegate runs as part of EnsureCreated, Migrate, and dotnet ef database update. Unlike HasData, you get a live DbContext: navigation properties, domain methods, and conditional logic all work.

Two things to keep in mind:

• Implement both UseSeeding and UseAsyncSeeding if you mix sync and async database creation paths (EF only calls the one matching the API used).
• The delegate runs every time migrations are applied, so the logic must be idempotent (more on that below).

Custom Initialization Logic

For more complex seeding, run custom code after your DbContext is configured. I typically create a DbInitializer class:

public static class DbInitializer
{
    public static async Task SeedAsync(AppDbContext context)
    {
        if (await context.Roles.AnyAsync())
        {
            return; // Already seeded
        }

        var adminRole = new Role("Admin");
        adminRole.AddPermission("users.read");
        adminRole.AddPermission("users.write");
        adminRole.AddPermission("orders.manage");

        var userRole = new Role("User");
        userRole.AddPermission("users.read");

        context.Roles.AddRange(adminRole, userRole);

        await context.SaveChangesAsync();
    }
}

Call it during application startup:

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await DbInitializer.SeedAsync(context);
}

app.Run();

This approach lets you use navigation properties, domain logic, and computed values. It also works well with DDD patterns where entities have private setters and factory methods.

Idempotent Seeding

Seed logic must be idempotent - running it multiple times should produce the same result. There are several patterns for this:

Check-Before-Insert

public static async Task SeedCurrenciesAsync(AppDbContext context)
{
    var existing = await context.Currencies
        .Select(c => c.Code)
        .ToHashSetAsync();

    var currencies = new List<Currency>
    {
        new("USD", "US Dollar"),
        new("EUR", "Euro"),
        new("GBP", "British Pound")
    };

    var newCurrencies = currencies
        .Where(c => !existing.Contains(c.Code))
        .ToList();

    if (newCurrencies.Count > 0)
    {
        context.Currencies.AddRange(newCurrencies);
        await context.SaveChangesAsync();
    }
}

Upsert Pattern

For data that might change between deployments:

public static async Task SeedConfigAsync(AppDbContext context)
{
    var configs = new Dictionary<string, string>
    {
        ["MaxRetryCount"] = "3",
        ["SessionTimeout"] = "30",
        ["DefaultPageSize"] = "25"
    };

    foreach (var (key, value) in configs)
    {
        var existing = await context.AppConfigs
            .FirstOrDefaultAsync(c => c.Key == key);

        if (existing is null)
        {
            context.AppConfigs.Add(new AppConfig(key, value));
        }
        else
        {
            existing.UpdateValue(value);
        }
    }

    await context.SaveChangesAsync();
}

Migration-Based Seeding

Sometimes you want seed data tied to a specific migration. Use the Up method of a migration to insert data:

public partial class AddDefaultCategories : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.InsertData(
            table: "Categories",
            columns: new[] { "Id", "Name", "SortOrder" },
            values: new object[,]
            {
                { new Guid("018e5f3a-0001-7000-8000-000000000001"), "Electronics", 1 },
                { new Guid("018e5f3a-0001-7000-8000-000000000002"), "Clothing", 2 },
                { new Guid("018e5f3a-0001-7000-8000-000000000003"), "Books", 3 }
            });
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DeleteData(
            table: "Categories",
            keyColumn: "Id",
            keyValues: new object[]
            {
                new Guid("018e5f3a-0001-7000-8000-000000000001"),
                new Guid("018e5f3a-0001-7000-8000-000000000002"),
                new Guid("018e5f3a-0001-7000-8000-000000000003")
            });
    }
}

This approach guarantees the data is inserted exactly once and in the right order relative to schema changes.

SQL Scripts

For large reference datasets or data that requires database-specific features, use raw SQL in migrations:

public partial class SeedCountries : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(
            File.ReadAllText("Migrations/Scripts/seed_countries.sql"));
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql("DELETE FROM Countries;");
    }
}

The SQL script approach gives you full control. You can use database-specific syntax, MERGE statements for upserts, and handle thousands of rows efficiently.

One caveat with File.ReadAllText: the path resolves against the working directory when the migration runs, which differs between dotnet ef database update and applying migrations at startup. Embed the script as an assembly resource instead if you apply migrations from multiple places:

migrationBuilder.Sql(
    ResourceHelper.ReadEmbedded("Migrations.Scripts.seed_countries.sql"));

Migration-based seeding also plays well with zero-downtime deployments, because the data ships atomically with the schema change that needs it.

Environment-Specific Seeding

Development needs test data. Production doesn't. Separate them:

using (var scope = app.Services.CreateScope())
{
    var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();

    // Always seed reference data
    await DbInitializer.SeedReferenceDataAsync(context);

    // Only seed test data in development
    if (app.Environment.IsDevelopment())
    {
        await DbInitializer.SeedTestDataAsync(context);
    }
}

Keep reference data (currencies, countries, roles) separate from test data (fake users, sample orders). Reference data goes to all environments. Test data stays in development.

For realistic test data at volume, use Bogus instead of hand-writing entities:

var userFaker = new Faker<User>()
    .CustomInstantiator(f => new User(
        f.Name.FirstName(),
        f.Name.LastName(),
        f.Internet.Email()));

var users = userFaker.Generate(500);

context.Users.AddRange(users);
await context.SaveChangesAsync();

Five hundred believable users in four lines beats copy-pasting new User(...) blocks.

Summary

Use HasData only for deterministic model-managed data with stable keys. Use UseSeeding or an explicit initializer for idempotent bootstrap logic, and migrations or reviewed scripts when the data must move with a schema version. Keep development fixtures separate so sample data can never become part of a production deployment by accident.

Why Multiple Databases?

A single DbContext pointing to a single database works for most applications. But eventually you might need to split things up. Common reasons include:

• Module isolation in a modular monolith - each module owns its data
• Read/write separation - queries go to a read replica
• Multi-tenancy - each tenant has a separate database
• Legacy integration - your app needs data from an existing database

EF Core handles all of these with multiple DbContext classes, each configured with its own connection string.

Defining Multiple DbContexts

Start by creating separate DbContext classes for each database:

public class OrdersDbContext : DbContext
{
    public OrdersDbContext(DbContextOptions<OrdersDbContext> options)
        : base(options) { }

    public DbSet<Order> Orders { get; set; }
    public DbSet<OrderLineItem> OrderLineItems { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(OrdersDbContext).Assembly,
            t => t.Namespace?.Contains("Orders") == true);
    }
}

public class CatalogDbContext : DbContext
{
    public CatalogDbContext(DbContextOptions<CatalogDbContext> options)
        : base(options) { }

    public DbSet<Product> Products { get; set; }
    public DbSet<Category> Categories { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(CatalogDbContext).Assembly,
            t => t.Namespace?.Contains("Catalog") == true);
    }
}

Each context only knows about its own entities. This enforces clear boundaries between modules.

Connection String Management

Store connection strings in appsettings.json:

{
  "ConnectionStrings": {
    "OrdersDb": "Host=localhost;Database=orders;Username=app;Password=secret",
    "CatalogDb": "Host=localhost;Database=catalog;Username=app;Password=secret"
  }
}

Then register each context in DI with its own connection string:

builder.Services.AddDbContext<OrdersDbContext>(options =>
    options.UseNpgsql(
        builder.Configuration.GetConnectionString("OrdersDb")));

builder.Services.AddDbContext<CatalogDbContext>(options =>
    options.UseNpgsql(
        builder.Configuration.GetConnectionString("CatalogDb")));

The generic DbContextOptions<T> parameter is what makes this work. Each context receives its own options instance. For more tips on configuring your DbContext, see my article on DbContext configuration best practices.

I also covered the same-database variant of this setup in Using Multiple EF Core DbContexts in a Single Application - the registration story is identical, only the connection strings differ.

Running Migrations Per Context

With multiple contexts, you must specify which context a migration belongs to. Use the --context flag:

# Create a migration for OrdersDbContext
dotnet ef migrations add InitialOrders \
    --context OrdersDbContext \
    --output-dir Migrations/Orders

# Create a migration for CatalogDbContext
dotnet ef migrations add InitialCatalog \
    --context CatalogDbContext \
    --output-dir Migrations/Catalog

Apply them separately:

dotnet ef database update --context OrdersDbContext
dotnet ef database update --context CatalogDbContext

Keep migrations in separate folders to avoid confusion, and name each folder after its module or context. For more deployment strategies, see EF Core migrations best practices.

Using Multiple Contexts in a Service

Inject both contexts when a service needs data from multiple databases:

public class OrderSummaryService
{
    private readonly OrdersDbContext _ordersDb;
    private readonly CatalogDbContext _catalogDb;

    public OrderSummaryService(
        OrdersDbContext ordersDb,
        CatalogDbContext catalogDb)
    {
        _ordersDb = ordersDb;
        _catalogDb = catalogDb;
    }

    public async Task<OrderSummaryDto?> GetOrderSummary(Guid orderId)
    {
        var order = await _ordersDb.Orders
            .AsNoTracking()
            .Include(o => o.LineItems)
            .FirstOrDefaultAsync(o => o.Id == orderId);

        if (order is null)
        {
            return null;
        }

        var productIds = order.LineItems
            .Select(li => li.ProductId)
            .ToList();

        var products = await _catalogDb.Products
            .AsNoTracking()
            .Where(p => productIds.Contains(p.Id))
            .ToDictionaryAsync(p => p.Id);

        return new OrderSummaryDto
        {
            OrderId = order.Id,
            Items = order.LineItems.Select(li => new LineItemDto
            {
                ProductName = products[li.ProductId].Name,
                Quantity = li.Quantity,
                Price = li.Price
            }).ToList()
        };
    }
}

Note that you cannot join across contexts in a single LINQ query. Each context only knows about its own database. You have to load data separately and combine in memory.

Read/Write Separation

A common pattern is routing read queries to a replica:

public class OrdersReadDbContext : DbContext
{
    public OrdersReadDbContext(
        DbContextOptions<OrdersReadDbContext> options)
        : base(options) { }

    public DbSet<Order> Orders { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(OrdersDbContext).Assembly,
            t => t.Namespace?.Contains("Orders") == true);
    }
}

Register it with the read replica connection string:

builder.Services.AddDbContext<OrdersReadDbContext>(options =>
    options.UseNpgsql(
            builder.Configuration.GetConnectionString("OrdersReadReplica"))
        .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));

Setting NoTracking as default makes sense for read-only contexts since you'll never call SaveChanges on them.

One gotcha with read replicas: replication lag. A write followed immediately by a read from the replica can return stale data. Route "read your own writes" queries (like fetching the entity you just created) to the primary, and reserve the replica for queries that tolerate slightly stale data.

Shared Entity Types Across Contexts

Sometimes two contexts need the same entity - for example, both Orders and Catalog reference a Product. Don't share entity classes directly. Instead, each context should have its own representation:

// In the Orders module
public class OrderProduct
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

// In the Catalog module
public class Product
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
    public Guid CategoryId { get; set; }
}

This keeps each module independent. If the Catalog module adds a column, the Orders module isn't affected.

Same Database, Multiple Contexts

You don't need multiple physical databases to benefit from multiple contexts. In a modular monolith, a common setup is one database with a schema per module, and one DbContext per schema:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.HasDefaultSchema("orders");
}

You get the module boundaries and independent migrations without the operational cost of extra databases. I cover the tradeoffs in modular monolith data isolation.

Cross-Database Transactions

EF Core doesn't support distributed transactions across databases out of the box. TransactionScope with two connections requires a distributed transaction coordinator, which only works on Windows with SQL Server and has no place in cloud-native systems.

If you need atomicity across two databases, consider:

• The outbox pattern - write to a local outbox table, then process asynchronously
• Eventual consistency with domain events
• A saga or process manager for complex workflows

Summary

Give each database its own DbContext, options, migration history, and model ownership. Queries do not join across those boundaries, and a local EF transaction cannot make independent databases atomic. Coordinate cross-database workflows with idempotent messages, an outbox, or a saga instead of hiding the boundary.

A database operation can fail even when the query and data are valid. EF Core execution strategies handle the retry loop when you define the correct transactional boundary.

Transient Failures Are Normal

In cloud environments, database connections fail. Load balancers rotate. SQL Azure throttles requests. Network hiccups happen. These are transient failures - they succeed if you retry.

Without retry logic, a brief network blip causes 500 errors for your users. EF Core's execution strategy solves this by automatically retrying failed operations.

Enabling Retry Logic

SQL Server / Azure SQL

builder.Services.AddDbContext<ApplicationDbContext>(options =>
{
    options.UseSqlServer(connectionString, sqlOptions =>
    {
        sqlOptions.EnableRetryOnFailure(
            maxRetryCount: 5,
            maxRetryDelay: TimeSpan.FromSeconds(30),
            errorNumbersToAdd: null);
    });
});

PostgreSQL (Npgsql)

builder.Services.AddDbContext<ApplicationDbContext>(options =>
{
    options.UseNpgsql(connectionString, npgsqlOptions =>
    {
        npgsqlOptions.EnableRetryOnFailure(
            maxRetryCount: 5,
            maxRetryDelay: TimeSpan.FromSeconds(30),
            errorCodesToAdd: null);
    });
});

Both use exponential backoff with jitter by default.

What Gets Retried?

EF Core retries these operations:

• SaveChangesAsync()
• ToListAsync(), FirstOrDefaultAsync(), etc.
• Any LINQ query execution

It retries only transient SQL errors. Constraint violations, syntax errors, and other non-transient failures are not retried.

SQL Server Transient Error Numbers

The default transient error list for SQL Server includes, among others:

• -2: Timeout
• 20: Instance error
• 64: Connection error
• 233: Connection closed
• 10053: Transport error
• 10054: Connection reset
• 10060: Connection timeout
• 40143: Throttled (Azure SQL)
• 40197: Service error (Azure SQL)
• 40501: Service busy (Azure SQL)
• 40613: Database unavailable (Azure SQL)
• 49918: Not enough resources (Azure SQL)
• 49919: Too many requests (Azure SQL)
• 49920: Too many requests (Azure SQL)

You can add custom error numbers:

sqlOptions.EnableRetryOnFailure(
    maxRetryCount: 5,
    maxRetryDelay: TimeSpan.FromSeconds(30),
    errorNumbersToAdd: [4060, 18401]);

The Transaction Problem

Here's the critical pitfall. Retries don't work with manual transactions:

// ❌ This throws InvalidOperationException with retry enabled
using var transaction = await _db.Database.BeginTransactionAsync();

order.Status = OrderStatus.Confirmed;
await _db.SaveChangesAsync();

payment.Status = PaymentStatus.Captured;
await _db.SaveChangesAsync();

await transaction.CommitAsync();

Why? If the first SaveChangesAsync succeeds but the second fails, EF Core can't retry the second without replaying the first. The retry strategy doesn't know about your transaction boundaries.

The Fix: CreateExecutionStrategy

var strategy = _db.Database.CreateExecutionStrategy();

await strategy.ExecuteAsync(async () =>
{
    using var transaction = await _db.Database.BeginTransactionAsync();

    order.Status = OrderStatus.Confirmed;
    await _db.SaveChangesAsync();

    payment.Status = PaymentStatus.Captured;
    await _db.SaveChangesAsync();

    await transaction.CommitAsync();
});

ExecuteAsync wraps the entire operation - including the transaction - as a single retriable unit. If any step fails with a transient error, the whole block is retried from the beginning.

Custom Execution Strategy

For fine-grained control, create a custom strategy:

public class CustomRetryStrategy : SqlServerRetryingExecutionStrategy
{
    private readonly ILogger<CustomRetryStrategy> _logger;

    public CustomRetryStrategy(
        ExecutionStrategyDependencies dependencies,
        int maxRetryCount,
        TimeSpan maxRetryDelay,
        ILogger<CustomRetryStrategy> logger)
        : base(dependencies, maxRetryCount, maxRetryDelay, null)
    {
        _logger = logger;
    }

    protected override bool ShouldRetryOn(Exception exception)
    {
        var shouldRetry = base.ShouldRetryOn(exception);

        if (shouldRetry)
        {
            _logger.LogWarning(exception,
                "Transient database error. Retrying...");
        }

        return shouldRetry;
    }

    protected override TimeSpan? GetNextDelay(Exception lastException)
    {
        var delay = base.GetNextDelay(lastException);

        if (delay.HasValue)
        {
            _logger.LogWarning(
                "Retrying in {Delay}ms after error: {Message}",
                delay.Value.TotalMilliseconds,
                lastException.Message);
        }

        return delay;
    }
}

Register it (note the AddDbContext overload that exposes the service provider, so we can resolve the logger):

builder.Services.AddDbContext<ApplicationDbContext>((sp, options) =>
{
    options.UseSqlServer(connectionString, sqlOptions =>
    {
        sqlOptions.ExecutionStrategy(dependencies =>
            new CustomRetryStrategy(
                dependencies,
                maxRetryCount: 5,
                maxRetryDelay: TimeSpan.FromSeconds(30),
                sp.GetRequiredService<ILogger<CustomRetryStrategy>>()));
    });
});

Retry With Polly

For more advanced policies, combine EF Core with Polly. With Polly v8, that means a resilience pipeline:

var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        ShouldHandle = new PredicateBuilder()
            .Handle<SqlException>(ex => ex.IsTransient)
            .Handle<TimeoutException>(),
        MaxRetryAttempts = 3,
        BackoffType = DelayBackoffType.Exponential,
        Delay = TimeSpan.FromSeconds(1),
        OnRetry = args =>
        {
            logger.LogWarning(
                "Retry {Attempt} after {Delay}ms: {Error}",
                args.AttemptNumber,
                args.RetryDelay.TotalMilliseconds,
                args.Outcome.Exception?.Message);

            return ValueTask.CompletedTask;
        }
    })
    .Build();

await pipeline.ExecuteAsync(async ct =>
{
    await _db.SaveChangesAsync(ct);
});

But in most cases, EF Core's built-in retry is sufficient - it already knows which provider errors are transient. Use Polly when you need circuit breakers or more complex resilience patterns, and avoid stacking Polly retries on top of EnableRetryOnFailure (you'd multiply the attempts).

Idempotency Matters

Retries mean your operation might execute more than once. Make sure your operations are idempotent.

Here's the subtle failure mode: the INSERT commits on the server, but the connection drops before the acknowledgment reaches your app. EF Core sees a transient error and retries. With database-generated keys, you get a duplicate row; with a client-generated key, the retry fails on the primary key violation.

// ❌ Not idempotent - a retry can re-execute an insert that already committed
var order = new Order { Id = Guid.NewGuid(), Total = 100 };
_db.Orders.Add(order);
await _db.SaveChangesAsync();

// ✅ Idempotent - upsert pattern
var order = await _db.Orders.FindAsync(orderId);
if (order is null)
{
    order = new Order { Id = orderId, Total = 100 };
    _db.Orders.Add(order);
}
else
{
    order.Total = 100;
}
await _db.SaveChangesAsync();

Or use the Inbox Pattern for message consumers.

Health Check Integration

Monitor connection health alongside retry:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString,
        name: "sql-server",
        timeout: TimeSpan.FromSeconds(5),
        tags: ["db", "ready"]);

Summary

Enable the provider's retry strategy for transient database failures. When you open an explicit transaction, execute the entire transaction through CreateExecutionStrategy so a retry cannot replay only half the work. Assume the final commit can be ambiguous and give externally visible operations an idempotency strategy.

Application code and database schema do not switch versions at exactly the same instant. During a rolling deployment, old and new instances must both work against the same intermediate schema.

The Deployment Problem

In a typical deployment, you update the database schema and deploy new application code at the same time. If the migration takes 30 seconds but the deployment takes 2 minutes, there's a window where the old code runs against the new schema - or the new code runs against the old schema.

Either scenario can cause errors. Renaming a column breaks the old code. Removing a column breaks queries that reference it. This is why naive migrations cause downtime.

The Expand-Contract Pattern

The expand-contract pattern splits every breaking change into three safe steps:

1. Expand - add the new structure alongside the old one
2. Migrate - move data and update code to use the new structure
3. Contract - remove the old structure once nothing depends on it

Each step is deployed independently. At no point does old code break, because the old structure is still present during the expand and migrate phases.

Additive-Only Migrations

The safest migrations only add things:

// ✅ Safe - additive changes
migrationBuilder.AddColumn<string>(
    name: "PhoneNumber",
    table: "Customers",
    nullable: true); // Must be nullable or have a default

migrationBuilder.CreateTable(
    name: "CustomerPreferences",
    columns: table => new
    {
        Id = table.Column<Guid>(),
        CustomerId = table.Column<Guid>(),
        Theme = table.Column<string>(defaultValue: "light")
    });

migrationBuilder.CreateIndex(
    name: "IX_Orders_CustomerId",
    table: "Orders",
    column: "CustomerId");

Adding nullable columns and new tables is normally compatible with old code because it ignores the new structures. Index creation is logically additive but can still block writes or consume substantial resources, so use the provider's online or concurrent option and test it on production-scale data.

// ❌ Dangerous - breaking changes
migrationBuilder.DropColumn(name: "Phone", table: "Customers");
migrationBuilder.RenameColumn(
    name: "Name", table: "Products", newName: "Title");
migrationBuilder.AlterColumn<string>(
    name: "Email", table: "Customers", nullable: false);

Dropping columns, renaming columns, and making nullable columns required are all breaking changes. They need the expand-contract pattern.

How Do You Rename a Column Without Downtime?

Renaming a column is one of the most common breaking changes. Here's how to do it safely with EF Core across three deployments.

Step 1: Expand - Add the New Column

public partial class AddTitleColumn : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.AddColumn<string>(
            name: "Title",
            table: "Products",
            nullable: true);

        migrationBuilder.Sql(
            @"UPDATE ""Products"" SET ""Title"" = ""Name""");
    }
}

Deploy this migration. Both Name and Title columns exist. Old code uses Name, new code doesn't exist yet.

Step 2: Migrate - Write to Both, Read From New

Update your DbContext configuration to map the entity to the new column:

public class ProductConfiguration : IEntityTypeConfiguration<Product>
{
    public void Configure(EntityTypeBuilder<Product> builder)
    {
        builder.Property(p => p.Title)
            .HasColumnName("Title");

        // Ignore the old property in the model
        builder.Ignore(p => p.Name);
    }
}

If other services still write to the old column, add a trigger or application-level sync to keep both columns in sync:

public partial class SyncTitleAndName : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(@"
            CREATE OR REPLACE FUNCTION sync_product_title()
            RETURNS TRIGGER AS $$
            BEGIN
                IF TG_OP = 'INSERT' THEN
                    IF NEW.""Title"" IS NULL THEN
                        NEW.""Title"" = NEW.""Name"";
                    ELSIF NEW.""Name"" IS NULL THEN
                        NEW.""Name"" = NEW.""Title"";
                    END IF;
                ELSIF NEW.""Title"" IS DISTINCT FROM OLD.""Title"" THEN
                    NEW.""Name"" = NEW.""Title"";
                ELSIF NEW.""Name"" IS DISTINCT FROM OLD.""Name"" THEN
                    NEW.""Title"" = NEW.""Name"";
                END IF;
                RETURN NEW;
            END;
            $$ LANGUAGE plpgsql;

            CREATE TRIGGER trg_sync_product_title
            BEFORE INSERT OR UPDATE ON ""Products""
            FOR EACH ROW EXECUTE FUNCTION sync_product_title();
        ");
    }
}

The trigger must fire on INSERT OR UPDATE, not just updates. Old code inserts rows with only Name set, new code inserts rows with only Title set, and an update-only trigger would leave the other column NULL - exactly the inconsistency this whole dance exists to prevent.

Deploy. All code works - old code reads/writes Name, new code reads/writes Title, and the trigger keeps them in sync.

Step 3: Contract - Remove the Old Column

Once no running code references Name, clean up:

public partial class DropNameColumn : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(
            @"DROP TRIGGER IF EXISTS trg_sync_product_title
              ON ""Products""");

        migrationBuilder.DropColumn(
            name: "Name",
            table: "Products");
    }
}

Three deployments, zero downtime.

Non-Nullable Column Strategy

Adding a required column to an existing table breaks if there's existing data. The safe approach:

// Step 1: Add as nullable with a default
migrationBuilder.AddColumn<string>(
    name: "Region",
    table: "Customers",
    nullable: true,
    defaultValue: "US");

// Step 2: Backfill existing rows
migrationBuilder.Sql(
    @"UPDATE ""Customers"" SET ""Region"" = 'US' WHERE ""Region"" IS NULL");

// Step 3: In a LATER migration, make it required
migrationBuilder.AlterColumn<string>(
    name: "Region",
    table: "Customers",
    nullable: false,
    defaultValue: "US");

Split steps 1-2 and step 3 into separate deployments. The application code should handle null values during the transition period.

Index Creation Without Blocking Writes

On large tables, a regular PostgreSQL CREATE INDEX allows reads but blocks writes on the target table. PostgreSQL also supports concurrent index creation:

public partial class AddOrderStatusIndex : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(
            @"CREATE INDEX CONCURRENTLY ""IX_Orders_Status""
              ON ""Orders"" (""Status"");",
            suppressTransaction: true);
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(
            @"DROP INDEX CONCURRENTLY IF EXISTS ""IX_Orders_Status"";",
            suppressTransaction: true);
    }
}

CREATE INDEX CONCURRENTLY builds the index without blocking writes. The concurrent create and drop commands both require suppressTransaction: true because PostgreSQL refuses to run either one inside a transaction block. The deployment runner must also execute the generated script as written instead of wrapping the entire file in its own transaction. The build still performs extra scans, consumes I/O, and may wait for old transactions to finish.

Keep the concurrent build in a dedicated migration with no later schema operations. It cannot be atomic with EF's migrations-history insert, and a failed build can leave an invalid index that still consumes write overhead. Inspect and remove that invalid index before retrying rather than adding IF NOT EXISTS to the create command.

I cover more deployment strategies in EF Core migrations best practices.

Applying Migrations in Production

Don't call Database.Migrate() at startup in production. It holds a lock, runs synchronously, and can fail in ways that leave the database in a partial state.

Instead, run migrations as a separate deployment step:

# Run migrations from CI/CD pipeline
dotnet ef database update --connection "$CONNECTION_STRING"

Or use a dedicated migration runner:

// In a console app or init container (host is the built IHost)
using var scope = host.Services.CreateScope();
var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();

var pending = await context.Database.GetPendingMigrationsAsync();
if (pending.Any())
{
    await context.Database.MigrateAsync();
}

Run migrations before deploying new application code. The expand phase ensures backwards compatibility, so the old code keeps working while migrations run.

Migration Checklist

Before deploying a migration to production, verify:

• Can the old application code run against the new schema?
• Can the new application code run against the old schema?
• Are all new columns nullable or have defaults?
• Are destructive changes (drops, renames) in a separate contract migration?
• Have large table operations been tested for lock duration?

Summary

Expand the schema so old and new application versions can run together, migrate reads and writes, and contract only after the old path is gone. Backfill required data in bounded batches and treat index builds or table rewrites as operational work even when the schema change is additive. Run migrations from the deployment pipeline and verify both forward compatibility and rollback behavior before production.

Every EF Core migration has a Down method, so rollbacks should be trivial. And they are, right up until someone deletes the migration file before reverting the database.

Now the history table lists a migration your project no longer has, database update cannot generate the revert SQL, and the model snapshot disagrees with both. The fix at that point is manual surgery.

The rollback commands are simple. What matters is the order, and which environment you are pointing at.

How Do You Undo the Last Applied Migration?

Say your history looks like this:

dotnet ef migrations list

# 20260620093011_AddOrders (applied)
# 20260701141518_AddOrderNotes (applied)   <- want to undo this one

Step 1: revert the database to the previous migration. database update takes a target migration name and runs every Down between the current state and that target:

dotnet ef database update AddOrders

Step 2: remove the migration file. Only after the database no longer contains the migration:

dotnet ef migrations remove

migrations remove deletes the newest migration file and rewinds the model snapshot, which is the part people forget exists. Doing it by hand (deleting the .cs files) leaves the snapshot describing a model with the migration still in it, and your next migration comes out empty or wrong. The snapshot is why the command exists; use it.

If you run the steps in the wrong order, migrations remove actually protects you: it refuses when the migration is applied, telling you to revert first. The people who get hurt are the ones who delete files manually or sync a branch that no longer contains the migration. Which brings us to git.

The Git Branch Trap

The most common way teams corrupt migration state has no EF command in it at all:

1. You apply AddOrderNotes to your local database while working on a branch.
2. The branch dies. You switch back to main.
3. The migration file is gone, but your local database still has the schema change and the history row.

EF Core now considers your database ahead of your project, and there is no file to generate Down SQL from. Your options, in order of preference:

• Recreate the database if it is disposable local dev. Fastest, cleanest.
• Check out the dead branch, revert, then switch. Run dotnet ef database update AddOrders while the migration file still exists in your working tree.
• Manual repair. Undo the schema change with hand-written SQL, then delete the history row:

DELETE FROM "__EFMigrationsHistory"
WHERE "MigrationId" = '20260701141518_AddOrderNotes';

The lesson: revert your local database before deleting or switching away from a branch with unmerged migrations. Make it muscle memory, the same way you run the practices from EF Core migrations best practices.

Rolling Back Migrations That Were Never Applied

If you added a migration and immediately regretted it (wrong name, model not ready), and it never ran anywhere:

dotnet ef migrations remove

Done. No database step, because there is nothing to revert. This is also the correct response to noticing a bad migration during code review: remove it, fix the model, add a fresh one. Never edit a generated migration's Up in place beyond documented customization, and never renumber or hand-rename them.

Production: Scripts and Bundles, Not CLI Commands

dotnet ef database update against production means SDK, source code, and DDL credentials on whatever machine runs it. Do not. The two production-grade options mirror how you deploy forward migrations.

Reviewed SQL scripts. Generate the revert SQL in CI, review it, run it through the same channel as any release script. Note the argument order, from current back to target:

dotnet ef migrations script AddOrderNotes AddOrders --output revert.sql

Migration bundles. A bundle accepts a target migration and will migrate down to it:

./efbundle AddOrders --connection "$DB_CONNECTION"

I covered why bundles beat startup migration, and how to build them in CI, in EF Core migration bundles.

Now the hard truth about production rollbacks: Down methods are only safe for additive changes. Reverting AddColumn runs DropColumn, and every value in that column is gone. Reverting a table rename or a data migration can be outright impossible to express. EF Core generates Down code mechanically; it has no idea whether the operation destroys data, and it will not warn you.

So before any production rollback:

• Read the generated SQL. All of it.
• If any statement drops or rewrites data, prefer rolling forward: write a new migration that reverses the intent while preserving data, and deploy it like any release.
• If you must roll back destructively, snapshot first (a backup, or SELECT INTO the affected columns).

This is also why the expand-and-contract pattern from zero-downtime migrations is worth the ceremony: when every migration is individually additive, every rollback is individually safe, and the old application version keeps working against the new schema in both directions. A rollback of code without a rollback of schema, the most common incident shape, becomes a non-event.

Rolling Back Everything

Two special targets are worth knowing. Reverting all migrations (torching the schema EF manages, useful for local resets):

dotnet ef database update 0

And listing what is applied versus pending when you are not sure where an environment stands:

dotnet ef migrations list --connection "$DB_CONNECTION"

For local development, database update 0 followed by database update is a poor man's rebuild; dropping and recreating the database is usually faster and also resets anything outside EF's control. If your integration tests fight schema drift, that reset-per-run approach is the reliable one, as I argued in fixing flaky Postgres integration tests.

The Rules That Keep Rollbacks Boring

• Applied migration, local database: database update <previous>, then migrations remove. In that order, always.
• Unapplied migration: migrations remove alone.
• Merged or deployed migration: it is immutable. Reverse it with a new forward migration, never by deleting history.
• Switching branches: revert the local database before abandoning a branch with unmerged migrations.
• Production: reviewed script or bundle with a target migration, backups before destructive Downs, and a strong bias toward roll-forward.

The deeper the migration is in shared history, the less "rollback" means running Down and the more it means writing a new Up that undoes the intent. That progression, and the full command reference, is laid out in EF Core migrations: a detailed guide.

Summary

Rolling back a migration is dotnet ef database update <previous-migration> followed by dotnet ef migrations remove, and the order is not negotiable: the database revert needs the Down method that lives in the file you are about to delete. migrations remove exists because the model snapshot must rewind with the file; deleting .cs files by hand corrupts the next migration.

Once a migration reaches a shared environment, stop thinking in terms of Down at all. Deployed history is append-only: reverse mistakes with new forward migrations, keep changes additive so old code and old schema stay mutually compatible, and save destructive rollbacks for databases you can afford to lose.

There are two moments a schema migration can run: when your pipeline deploys, or when your application boots.

Database.Migrate() in Program.cs picks the second, and it is the default in a thousand tutorials. It is also the option where a broken migration takes down production instead of failing a pipeline step, where three replicas race to alter the same table, and where your web app carries DDL permissions it should not have.

Migration bundles exist to make the first option as easy as the second. One command produces a self-contained executable; your pipeline runs it before the new code ships.

Why Migrate-on-Startup Bites

The convenient version looks like this:

using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
}

app.Run();

Four operational risks follow:

• Replica races. Kubernetes starts three pods; all three call MigrateAsync simultaneously. EF Core takes locks and usually survives, but "usually" is doing heavy lifting, and on some providers concurrent migrators can deadlock or half-apply.
• Failure lands in the wrong place. A migration that times out on a large table turns into a crash-looping app and an outage. The same failure in a pipeline step is a red build and a rollback, with the old version still serving.
• Permissions. The app's runtime identity now needs ALTER, CREATE, DROP. Least privilege dies at line one of Program.cs.
• Rolling deploys invert the order. During a rolling update, the new pod migrates the schema while old pods still run old queries against it. You need zero-downtime discipline either way, but startup migration removes your control over the timing.

Startup migration is defensible in exactly one place: local development and single-instance internal tools. Everywhere else, the schema change belongs to the deployment, not the process.

Building a Bundle

The tooling is part of dotnet-ef:

dotnet tool install --global dotnet-ef

dotnet ef migrations bundle \
  --project src/MyApp.Infrastructure \
  --startup-project src/MyApp.Api \
  --self-contained -r linux-x64 \
  --output efbundle

The output is a single executable containing your compiled migrations, your model snapshot, and, with --self-contained, the .NET runtime itself (which makes it weigh tens of megabytes). The pipeline agent or init container that runs it needs nothing installed.

Running it is equally boring, which is the point:

./efbundle --connection "Host=db;Database=myapp;Username=migrator;Password=$DB_PASSWORD"

The bundle reads the migrations history table, applies only what is pending, and exits non-zero on failure. It also accepts a target migration as an argument, which makes it usable for controlled rollbacks:

./efbundle AddOrderTable --connection "..."

Note the connection string is supplied at run time, not baked in at build time. One artifact promotes through dev, staging, and production, credentials come from the environment, and the migration runs under a dedicated migrator database role, not the app's identity.

Wiring It into a Pipeline

Here is a GitHub Actions workflow that builds the bundle once and executes it before the deploy step:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Build migration bundle
        run: |
          dotnet tool restore
          dotnet ef migrations bundle \
            --project src/MyApp.Infrastructure \
            --startup-project src/MyApp.Api \
            --self-contained -r linux-x64 \
            --output efbundle

      - uses: actions/upload-artifact@v4
        with:
          name: efbundle
          path: efbundle

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: efbundle

      - name: Apply migrations
        run: |
          chmod +x efbundle
          ./efbundle --connection "${{ secrets.DB_CONNECTION }}"

      - name: Deploy application
        run: ./deploy.sh

The ordering encodes the contract: schema first, code second, and only if the schema step succeeded.

That contract is also what makes expand-and-contract migrations work, since the old code must keep running against the new schema for the duration of the rollout.

In containerized setups, the same bundle runs as a Kubernetes init container or a one-off job before the rollout. Because it is self-contained, the migration image can be FROM debian:stable-slim with the bundle copied in, no SDK layer.

If you orchestrate local development with Aspire, migrations fit a similar "separate executor" model there too; I showed that pattern in applying EF Core migrations with Aspire.

Bundles vs SQL Scripts vs Migrate-on-Startup

The other pipeline-friendly option is generating an idempotent SQL script:

dotnet ef migrations script --idempotent --output migrations.sql

Scripts have one real advantage: a DBA can read, review, and hand-tune the exact SQL before it runs, and script execution slots into organizations where database changes go through a review gate. The costs are tooling (you need sqlcmd/psql on the agent) and drift risk if someone edits the script after review.

My decision line:

• Bundles: teams that own their database, automated pipelines, containers. Least ceremony, artifact matches what EF would do exactly.
• Idempotent scripts: regulated environments, mandatory DBA review, or migrations that need hand-tuned locking hints on giant tables.
• Migrate-on-startup: local dev only.

Whichever you pick, the deeper habits, small reversible migrations, never editing an applied migration, reviewing generated SQL, come from EF Core migrations best practices, and the fundamentals of the migration system itself are in EF Core migrations: a detailed guide.

Operational Details Worth Knowing

• The bundle must match the deploy. Build it in the same pipeline run as the app artifact, from the same commit. A bundle from yesterday's build applying against today's code is drift by construction.
• Timeouts. Long-running migrations on big tables inherit the command timeout in the connection string; set Command Timeout=600 (or provider equivalent) explicitly for heavyweight releases.
• Concurrency guard. Pipelines can race too, if two deploys overlap. Serialize the deploy job per environment; the pipeline is the right place for that lock, not the database.
• EF 9+ warns loudly when the model has changes not covered by any migration, which catches the "forgot to add a migration" failure in CI instead of production. I covered that check in fixing PendingModelChangesWarning.

Summary

A migration bundle turns "apply schema changes" into a single self-contained executable your pipeline runs as a first-class deploy step. Failures become red builds instead of crash-looping pods, the app sheds its DDL permissions, replicas stop racing, and one artifact promotes across environments with the connection string supplied at run time.

dotnet ef migrations bundle in CI, ./efbundle --connection before the deploy, schema before code. Keep Database.Migrate() for localhost, where it belongs.

PostgreSQL is not SQL Server with a different connection string. A clean provider setup gives you those PostgreSQL capabilities without leaking database-specific details through the whole application.

Why PostgreSQL With EF Core?

PostgreSQL offers features that SQL Server doesn't - JSONB columns, native array types, full-text search, and range types. It's also free and runs everywhere. The Npgsql provider for EF Core gives you access to all of these features.

Npgsql is the official PostgreSQL provider for EF Core, distributed as the Npgsql.EntityFrameworkCore.PostgreSQL NuGet package. It is mature, actively maintained, and exposes PostgreSQL-specific functionality through EF Core's configuration and query APIs.

Setting Up the Npgsql Provider

If you don't have PostgreSQL running yet, Docker is the quickest way:

docker run -d --name postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:17

Install the NuGet package:

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Configure your DbContext:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Database")));

Connection string in appsettings.json:

{
  "ConnectionStrings": {
    "Database": "Host=localhost;Port=5432;Database=myapp;Username=postgres;Password=postgres"
  }
}

That's all you need to get started. EF Core migrations and queries work the same way as with SQL Server.

Snake_case Naming Convention

PostgreSQL conventions use snake_case for table and column names. By default, EF Core generates PascalCase names, which work but look out of place.

Use the naming conventions package:

dotnet add package EFCore.NamingConventions

Configure it:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString)
           .UseSnakeCaseNamingConvention());

Now an entity like this:

public class Order
{
    public Guid Id { get; set; }
    public DateTime CreatedAt { get; set; }
    public OrderStatus Status { get; set; }
    public decimal TotalAmount { get; set; }
}

Generates a table with snake_case columns:

CREATE TABLE orders (
    id uuid NOT NULL,
    created_at timestamp with time zone NOT NULL,
    status integer NOT NULL,
    total_amount numeric NOT NULL,
    CONSTRAINT pk_orders PRIMARY KEY (id)
);

JSONB Columns

PostgreSQL's jsonb type stores JSON data in a binary format that supports indexing and querying. EF Core maps this natively with owned types (the Npgsql provider supports ToJson since version 8):

public class Product
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public ProductMetadata Metadata { get; set; }
}

public class ProductMetadata
{
    public string Brand { get; set; }
    public int? ReleaseYear { get; set; }
    public List<string> Tags { get; set; }
}

Stick to regular properties, primitive collections, and nested owned types inside the JSON type. Dictionary properties are not supported in ToJson mappings.

Configure as JSON:

public void Configure(EntityTypeBuilder<Product> builder)
{
    builder.OwnsOne(p => p.Metadata, meta =>
    {
        meta.ToJson();
    });
}

You can query into JSONB columns:

var products = await context.Products
    .Where(p => p.Metadata.Brand == "Contoso")
    .ToListAsync();

EF Core translates this into a PostgreSQL JSON query. For more complex queries, you can use raw SQL with JSON operators.

Array Types

PostgreSQL natively supports array columns. Npgsql maps .NET arrays and lists directly:

public class Product
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string[] Tags { get; set; }
    public List<int> Ratings { get; set; }
}

No special configuration needed. EF Core generates:

CREATE TABLE products (
    id uuid NOT NULL,
    name text NOT NULL,
    tags text[] NOT NULL,
    ratings integer[] NOT NULL
);

Query array columns with LINQ:

// Products that contain a specific tag
var products = await context.Products
    .Where(p => p.Tags.Contains("electronics"))
    .ToListAsync();

// Products with any matching tag
var searchTags = new[] { "electronics", "sale" };
var matching = await context.Products
    .Where(p => p.Tags.Any(t => searchTags.Contains(t)))
    .ToListAsync();

Arrays are great for simple lists of values where you don't need a separate table.

Full-Text Search

PostgreSQL has powerful built-in full-text search. Npgsql exposes it through EF Core:

var results = await context.Products
    .Where(p => EF.Functions.ToTsVector("english", p.Name + " " + p.Description)
        .Matches(EF.Functions.ToTsQuery("english", "laptop & gaming")))
    .ToListAsync();

For better performance, add a generated tsvector column:

public class Product
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public NpgsqlTsVector SearchVector { get; set; }
}

Configure it:

builder.Property(p => p.SearchVector)
    .HasComputedColumnSql(
        @"to_tsvector('english', coalesce(name, '') || ' ' || coalesce(description, ''))",
        stored: true);

builder.HasIndex(p => p.SearchVector)
    .HasMethod("GIN");

Now queries use the precomputed index:

var results = await context.Products
    .Where(p => p.SearchVector.Matches(
        EF.Functions.ToTsQuery("english", "laptop & gaming")))
    .OrderByDescending(p => p.SearchVector.Rank(
        EF.Functions.ToTsQuery("english", "laptop & gaming")))
    .ToListAsync();

With an appropriate GIN index, PostgreSQL full-text search scales better than an unindexed LIKE or ILIKE scan on large datasets.

PostgreSQL-Specific Features

A few more features worth knowing:

UUID Primary Keys

PostgreSQL has native uuid support. Use Guid properties and they map to uuid columns:

builder.Property(o => o.Id)
    .HasDefaultValueSql("gen_random_uuid()");

Enum Mapping

Map .NET enums to PostgreSQL enum types:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString, npgsqlOptions =>
        npgsqlOptions.MapEnum<OrderStatus>("order_status")));

The UTC Timestamp Rule

This is the one that surprises everyone migrating from SQL Server. PostgreSQL's timestamptz stores instants in UTC, and since Npgsql 6, writing a DateTime with Kind = Unspecified or Local to a timestamptz column throws an exception.

Use DateTime.UtcNow for generated instants, or accept DateTimeOffset at the boundary and normalize it to offset zero before writing. Npgsql maps DateTimeOffset to timestamptz, but rejects non-zero offsets because PostgreSQL stores the UTC instant rather than the original offset.

If you're porting a legacy codebase and can't fix every timestamp at once, there's an escape hatch that restores the old behavior:

// Opt back into pre-Npgsql-6 behavior (not recommended for new code)
AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", true);

Treat that switch as a migration aid, not a solution.

Stored Procedures and Functions

PostgreSQL functions work well with EF Core too - I cover calling them (and when to use them) in stored procedures and functions with EF Core and PostgreSQL.

Vector Search

If you're building AI features, the pgvector extension turns PostgreSQL into a capable vector database. See getting started with pgvector in .NET.

Summary

Start with Npgsql and make naming and UTC conventions explicit at the model boundary. Then use PostgreSQL features such as JSONB, arrays, full-text search, and native enums where they simplify the data model. Provider-specific capabilities are an advantage when the choice is deliberate and isolated from unrelated application code.

Your app works on SQL Server, or on an older Npgsql version. You point it at PostgreSQL with the current stack and the first save throws:

"Cannot write DateTime with Kind=Unspecified to PostgreSQL type 'timestamp with time zone', only UTC is supported."

Or the Kind=Local variant, same exception, different offender. A search turns up a one-line fix, the Npgsql.EnableLegacyTimestampBehavior switch, at the top of every result.

Do not start there. The exception is Npgsql refusing to guess what your ambiguous DateTime means, and the switch tells it to go back to guessing. The real fix is making your DateTime values unambiguous, and it is not much more work.

Why Npgsql 6+ Is Strict

PostgreSQL has two timestamp types, and they mean different things:

• timestamp with time zone (timestamptz): an absolute instant. Postgres normalizes it to UTC internally; no zone is stored.
• timestamp without time zone (timestamp): a wall-clock reading with no inherent zone. "2026-07-03 09:00" and good luck knowing where.

.NET's DateTime carries a Kind flag: Utc, Local, or Unspecified. Before Npgsql 6, the driver accepted ambiguous values and could let time-zone assumptions surface later as stored-data bugs.

Since Npgsql 6, the mapping is principled:

• DateTime with Kind=Utc maps to timestamptz. This is the default mapping for DateTime properties in EF Core with Npgsql.
• DateTime with Kind=Local or Unspecified maps to timestamp only.
• Writing a non-UTC Kind to a timestamptz column is an error, the one you are staring at, because interpreting it would require assuming a time zone.

Reading is symmetric: timestamptz comes back as Kind=Utc. The driver is enforcing a simple invariant: absolute instants cross the wire in UTC.

Step 1: Find the Offending Value

The exception tells you the Kind but not the property. Typical sources, starting with the most common boundaries:

• DateTime.Now anywhere in the codebase. It produces Kind=Local. Grep for it; every hit is a bug in a service that stores instants.
• JSON deserialization. A payload with "2026-07-03T09:00:00" (no offset) deserializes to Kind=Unspecified. API DTOs are the top source of Unspecified values.
• Database reads from other systems, CSV imports, and DateTime.Parse without DateTimeStyles.AdjustToUniversal.
• Values constructed with new DateTime(...) without specifying a kind: Unspecified by default.
• Entities materialized by other ORMs or Dapper from timestamp columns.

Temporarily enabling sensitive data logging in EF Core query logging shows the parameter values, which usually pinpoints the property fast.

Step 2: Normalize at the Boundary

The durable fix is a rule: inside the application, instants are UTC. Convert at the edges where non-UTC values enter.

Producing timestamps yourself is the easy case:

// wrong for stored instants
order.CreatedAt = DateTime.Now;

// right
order.CreatedAt = DateTime.UtcNow;

Better still, take time as a dependency with .NET 8's TimeProvider (timeProvider.GetUtcNow()), which also makes the code testable.

API input deserves an explicit contract. If clients send offsets (2026-07-03T09:00:00+02:00), bind to DateTimeOffset and convert:

public record CreateBookingRequest(DateTimeOffset StartsAt);

var booking = new Booking
{
    StartsAtUtc = request.StartsAt.UtcDateTime // Kind=Utc, unambiguous
};

If clients send zoneless wall-clock times, you must know the intended zone and say so in code:

var zone = TimeZoneInfo.FindSystemTimeZoneById("Europe/Oslo");

var utc = TimeZoneInfo.ConvertTimeToUtc(
    DateTime.SpecifyKind(request.StartsAt, DateTimeKind.Unspecified),
    zone);

Values you already know are UTC but arrive as Unspecified (a UTC string without the Z, a read from a legacy timestamp column) just need their Kind stamped:

var utc = DateTime.SpecifyKind(value, DateTimeKind.Utc);

SpecifyKind does not convert; it asserts. Only use it when the assertion is true.

Step 3: Enforce It in the Model

Boundary discipline decays as teams grow, so back it with a model-wide value converter that makes non-UTC values impossible to persist:

public class UtcDateTimeConverter : ValueConverter<DateTime, DateTime>
{
    public UtcDateTimeConverter()
        : base(
            v => v.Kind == DateTimeKind.Utc ? v : v.ToUniversalTime(),
            v => DateTime.SpecifyKind(v, DateTimeKind.Utc))
    {
    }
}

// In your DbContext:
protected override void ConfigureConventions(
    ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<DateTime>()
        .HaveConversion<UtcDateTimeConverter>();
}

One caveat to apply on purpose: ToUniversalTime() on an Unspecified value assumes the server's local zone, which is only correct if that assumption is. If you would rather fail loudly than guess, throw in the converter for Unspecified instead of converting. On containers pinned to UTC the distinction rarely bites, but decide, do not drift.

Registering converters model-wide like this is the same technique from custom model conventions in EF Core.

What About the Legacy Switch?

The escape hatch exists:

AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", true);

It restores pre-6 behavior: no Kind validation, timestamptz values read back as Kind=Local, and every ambiguity silently accepted. Legitimate use: a large legacy codebase mid-migration to Postgres, where you need the app running while you clean up call sites incrementally. Set it, file the tech-debt issue, and remove it when the converter and boundary fixes land.

What it is not: a fix. The exception was the only thing standing between you and timestamps that shift by your UTC offset depending on which server wrote them.

Choosing Types Going Forward

• Instants (created-at, occurred-at, expires-at): DateTime in UTC or DateTimeOffset, column timestamptz. Both work with Npgsql; DateTimeOffset must have offset zero on write, and the offset is not stored. I compared the two types in DateTime vs DateTimeOffset in C#.
• Wall-clock values (a clinic's opening hour, a scheduled local delivery slot): timestamp column via HasColumnType("timestamp without time zone") with Unspecified Kind, plus a separate time zone id column. Forcing these to UTC destroys information; they are not instants.
• Dates and times alone: DateOnly and TimeOnly map cleanly to date and time with Npgsql, and dodge the whole Kind circus.

If you are earlier in your Postgres journey, the setup fundamentals are in getting started with EF Core and PostgreSQL, and this error is worth solving properly before data accumulates, because rewriting mis-zoned historical timestamps later is somewhere between painful and impossible, the kind of surgery that needs a carefully staged migration.

Summary

The exception is Npgsql enforcing a good invariant: timestamptz holds absolute instants, and absolute instants must arrive as UTC. A DateTime with Kind=Local or Unspecified is a question, not an answer, and since version 6 the driver refuses to answer it for you.

Fix the sources: UtcNow (or TimeProvider) for generated timestamps, explicit offset or zone handling for external input, SpecifyKind only where UTC is already a fact. Back it with a model-wide UTC converter so the rule enforces itself, and reserve the legacy switch for migration bridges with an expiry date.

Get the invariant in place early. Every week it waits, more ambiguous timestamps land in your tables, and unlike code, stored data does not get fixed by a redeploy.

A migration is executable production code with permission to reshape your data. Treating it as generated plumbing hides locking, data-loss, and deployment-order risks until the change reaches a real database. Safe migrations are reviewed, scripted, tested, and deployed as deliberately as the application that depends on them.

Migrations Are Production Code

EF Core migrations work great on your local machine. You run dotnet ef database update, the schema changes, and life is good.

Production is different. You have:

• Multiple instances running the same database
• Zero-downtime deployments to maintain
• Rollback scenarios to plan for
• Data to preserve (you can't just drop and recreate)
• Team members creating conflicting migrations

EF Core migrations need the same discipline as any other production code. If you need a refresher on how migrations work mechanically, start with my detailed EF Core migrations guide - this article focuses on running them safely in production.

Creating Clean Migrations

One Migration Per Logical Change

Don't combine unrelated schema changes. If you're adding a column to Orders and creating a new Payments table, make two separate migrations:

dotnet ef migrations add AddShippingAddressToOrders
dotnet ef migrations add CreatePaymentsTable

Smaller migrations are easier to review, easier to roll back, and cause fewer merge conflicts.

Review Generated SQL

Always inspect what EF Core generates:

dotnet ef migrations script --idempotent

The idempotent flag checks the migrations history table and skips migrations that completed successfully. It does not make every statement independently retryable: a transaction-suppressed operation can succeed even if the migration later fails before its history row is recorded.

Review the output for:

• Unexpected DROP statements
• Missing indexes
• Data loss operations (column type changes, table drops)

Name Migrations Descriptively

✗ Migration1, Update2, Fix3
✓ AddShippingAddressToOrders, CreatePaymentMethodsTable, AddIndexOnOrderStatus

Migration names should describe the change. Future you will thank present you.

How Should You Apply Migrations in Production?

Option 1: SQL Scripts in CI/CD

Generate an idempotent SQL script and run it as a deployment step:

dotnet ef migrations script --idempotent -o migrations.sql

Then apply it (with psql for PostgreSQL, or the equivalent client for your database):

psql "$DATABASE_CONNECTION_STRING" -f migrations.sql

Pros: Full control, works with any deployment tool, can be reviewed before execution. Cons: Manual pipeline setup.

Option 2: Migration Bundles

EF Core 6+ supports migration bundles - self-contained executables that apply migrations:

dotnet ef migrations bundle --self-contained -o efbundle

Then in your deployment:

./efbundle --connection "Server=myserver;Database=mydb;..."

Pros: No SDK needed at deployment time, single file, idempotent by default. Cons: Bundle needs to match your target runtime.

Option 3: Migrate on Startup (Use With Caution)

using var scope = app.Services.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
await dbContext.Database.MigrateAsync();

Pros: Simple, automatic. Cons: Dangerous with multiple instances. Two instances starting simultaneously can conflict. Startup is slower. Failed migration blocks the application from starting.

I only recommend this for single-instance deployments or development environments.

Handling Data Migrations

Schema migrations change structure. Data migrations change content. Keep them separate.

Don't do this in a migration:

// Bad - mixing schema and complex data changes
migrationBuilder.Sql(@"
    UPDATE Orders
    SET Status = CASE
        WHEN OldStatus = 1 THEN 'Draft'
        WHEN OldStatus = 2 THEN 'Confirmed'
        ELSE 'Unknown'
    END;
    ALTER TABLE Orders DROP COLUMN OldStatus;
");

Do this instead:

1. Migration 1: Add new column
2. Deploy data migration script (or background job)
3. Migration 2: Drop old column

This multi-step approach is safer because you can verify the data migration worked before dropping the old column.

Zero-Downtime Migrations

Adding a column? Easy - old code ignores it, new code uses it.

Removing a column? Dangerous - old code might still reference it during rolling deployments.

The safe pattern for breaking changes:

Step 1: Expand - Add the new column/table. Deploy code that writes to both old and new.

Step 2: Migrate - Backfill data from old to new.

Step 3: Contract - Deploy code that only uses the new column. Then drop the old one.

This is called the expand-contract pattern. It ensures both the old and new versions of your application work at every step.

I go deeper on this in zero-downtime migrations with EF Core, and there's a practical demo using password hashing if you want to see the pattern applied end to end.

Handling Merge Conflicts

When two developers create migrations from the same base:

1. Developer A creates AddShippingAddress (snapshot → A)
2. Developer B creates AddPaymentMethod (snapshot → B)
3. When merged, the model snapshot has conflicts

Fix: after merging, recreate Developer B's migration:

# Remove B's migration
dotnet ef migrations remove

# Add it back (now based on A's snapshot)
dotnet ef migrations add AddPaymentMethod

Prevention: coordinate migrations. Only one migration branch should be in-flight at a time, or use a migration lock file.

Seeding Reference Data

Use migrations for reference data that your application requires:

migrationBuilder.InsertData(
    table: "OrderStatuses",
    columns: new[] { "Id", "Name" },
    values: new object[,]
    {
        { 1, "Draft" },
        { 2, "Confirmed" },
        { 3, "Shipped" },
        { 4, "Delivered" },
        { 5, "Cancelled" }
    });

For large datasets or dynamic data, use a separate seeding tool or script - not migrations. I compare the options (including UseSeeding from EF Core 9) in seeding data with EF Core.

Index Management

Always add indexes through migrations. EF Core creates some automatically, but you should be explicit about performance-critical ones:

migrationBuilder.CreateIndex(
    name: "IX_Orders_CustomerId_Status",
    table: "Orders",
    columns: new[] { "CustomerId", "Status" });

migrationBuilder.CreateIndex(
    name: "IX_Orders_CreatedAt",
    table: "Orders",
    column: "CreatedAt",
    descending: new[] { true });

Create indexes concurrently on PostgreSQL when a normal build would block writes:

migrationBuilder.Sql(
    @"CREATE INDEX CONCURRENTLY ""IX_Orders_CreatedAt""
      ON ""Orders"" (""CreatedAt"" DESC);",
    suppressTransaction: true);

PostgreSQL rejects CREATE INDEX CONCURRENTLY inside a transaction, so suppressTransaction: true is required. Put this operation in a dedicated migration and do not let the deployment runner wrap the generated script in an outer BEGIN/COMMIT block. Concurrent creation performs extra scans and can wait on long-running transactions, so it avoids blocking writes rather than making the build free of operational impact.

Transaction suppression also makes the migration non-atomic. If the build or a later command fails, PostgreSQL can leave an invalid or already-created index while EF has no migration-history row. Inspect the index state and drop an invalid index before retrying; do not hide the mismatch with IF NOT EXISTS.

My Recommended Pipeline

The key: migrations run before the application deploys. The database schema is always ahead of the application code.

Summary

Keep each migration focused, review the generated SQL, and test it against a realistic copy of the database. Deploy idempotent scripts or bundles from the pipeline rather than letting every application instance race at startup. For breaking changes, expand the schema first and remove the old shape only after all deployed code has moved away from it.

You upgrade a project to EF Core 9, run it, and MigrateAsync throws:

"The model for context 'AppDbContext' has pending changes. Add a new migration before updating the database."

You run dotnet ef migrations add Whatever, and the generated migration is empty, or contains nothing but updated seed rows. You apply it, and next week the error is back.

Welcome to one of the most-reported EF Core 9 upgrade issues. The check itself is a good idea: it catches genuinely missing migrations before they become production schema drift. But its most common trigger is not a forgotten migration. It is seed data that changes every time the model is built.

What Does EF Core 9 Actually Check?

Every migration you add updates the model snapshot (AppDbContextModelSnapshot.cs), a C# record of the model as of that migration. When migrations run, EF Core 9 compares the model your code builds right now against that snapshot. Any difference means: the last migration does not describe your current model.

Before EF 9 this drift was silent, and Migrate() happily brought the database up to the last migration while your model quietly disagreed with it. EF 9 promotes the mismatch from silent to fatal (when applying migrations at runtime) via PendingModelChangesWarning.

So the error has exactly two families of causes:

1. Real pending changes. You edited an entity or configuration and forgot to add a migration. The fix is the obvious one.
2. A model that never stabilizes. Something in model building produces a different model on every run, so no migration can ever catch up. This is the sneaky one.

First, Diagnose Honestly

Add a migration and read it:

dotnet ef migrations add Probe

• The migration has real operations (columns, indexes, tables): you had genuine drift. Rename it properly or keep it, apply it, done.
• The migration is empty or touches only UpdateData on seed rows with new timestamps or GUIDs: you have the dynamic-seed problem. Remove the probe (dotnet ef migrations remove) and read on.

The UpdateData calls are the tell. Look at what changed in them: a CreatedAt becoming a slightly later CreatedAt, or a key GUID becoming a different GUID. That value is computed at model build time.

The Sneaky Trigger: Dynamic Values in HasData

HasData seed data is part of the model. This compiles, works in EF 8, and is a time bomb:

modelBuilder.Entity<Role>().HasData(
    new Role
    {
        Id = Guid.NewGuid(),                // new value every model build
        Name = "Admin",
        CreatedAtUtc = DateTime.UtcNow      // new value every model build
    });

Every time EF Core builds the model, Guid.NewGuid() and DateTime.UtcNow produce fresh values. The snapshot recorded yesterday's values. The comparison can never succeed, so the pending-changes error is permanent, and every migration you add "fixes" it only until the next model build.

The same bug hides in subtler outfits:

• Environment.MachineName, Random, or config-dependent values in seed rows.
• Value converters or default values computed with non-deterministic expressions.
• Seed entities whose constructor sets CreatedAt = DateTime.UtcNow internally, so the literal in HasData looks innocent.

Fix 1: Make Seed Values Constant

HasData was always designed for static, hardcoded data with explicit keys. Give it exactly that:

modelBuilder.Entity<Role>().HasData(
    new Role
    {
        Id = Guid.Parse("8f3a2c1e-5b74-4d20-9c6f-1a2b3c4d5e6f"),
        Name = "Admin",
        CreatedAtUtc = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc)
    });

Stable values, stable model, and the snapshot matches forever. If typing GUIDs offends you, generate them once and paste them; the point is that they never change again. This constraint is also why HasData should stay small: reference data like roles, statuses, and countries, not test fixtures.

Fix 2: Move Seeding Out of the Model (EF 9's UseSeeding)

EF Core 9 added the better tool for anything dynamic: seeding callbacks that run as part of EnsureCreated/Migrate flows but live outside the model, so nothing about them affects the snapshot:

builder.Services.AddDbContext<AppDbContext>(options =>
    options
        .UseNpgsql(connectionString)
        .UseAsyncSeeding(async (context, _, ct) =>
        {
            var adminExists = await context.Set<Role>()
                .AnyAsync(r => r.Name == "Admin", ct);

            if (!adminExists)
            {
                context.Set<Role>().Add(new Role
                {
                    Id = Guid.NewGuid(),          // fine here
                    Name = "Admin",
                    CreatedAtUtc = DateTime.UtcNow // also fine
                });

                await context.SaveChangesAsync(ct);
            }
        })
        .UseSeeding((context, _) =>
        {
            // synchronous twin, used by EnsureCreated and design-time tooling
        }));

Because the callback is ordinary code against the context, dynamic values, lookups, and conditional logic are all legal. The tradeoff is that it runs where migrations run; if you apply migrations from a pipeline instead of the app (which you should, see migration bundles), run your seeder as an explicit step in that pipeline or at app startup as idempotent code.

I compared all the seeding options, HasData, seeding callbacks, and hand-rolled startup seeders, in seeding data in EF Core.

Fix 3 (Last Resort): Suppress the Warning

If you are mid-upgrade and need the app running today:

options.ConfigureWarnings(w =>
    w.Ignore(RelationalEventId.PendingModelChangesWarning));

Be honest about what this does: it turns the drift detector back off, EF 8 style. The real missing-migration bug it exists to catch, someone edits an entity and ships without a migration, sails through silently again. Suppress it as a bridge, fix the seed data, then remove the suppression.

A better long-term guard is failing CI when the model drifts. One option is running dotnet ef migrations has-pending-model-changes in the pipeline:

dotnet ef migrations has-pending-model-changes

The command exits non-zero when pending changes exist, so it fails the pipeline step on its own. Or assert the same in a test through context.Database.HasPendingModelChanges(). That converts the whole class of problem into a red pull request, which is where schema mistakes are cheapest, in line with EF Core migrations best practices.

Other Legitimate Causes Worth Ruling Out

If your seeds are static and the error persists, check for:

• Provider or version switches. Building the model with a different provider (SQL Server locally, PostgreSQL in CI) produces provider-specific model differences against a snapshot generated with the other one. One provider per snapshot lineage.
• Conditional model building. if statements in OnModelCreating keyed on environment or config make the model non-deterministic across machines. Push that variability out of the model.
• Manually edited snapshots. A merge conflict resolved by hand-editing ModelSnapshot.cs can leave it describing a model no code produces. Regenerate by removing and re-adding the latest migration in a clean state, per how to roll back an EF Core migration.

Summary

PendingModelChangesWarning is EF Core 9 refusing to migrate a database from a model that has drifted past its last migration. When the drift is real, the fix is the migration you forgot. When the error will not die and every probe migration just rewrites seed timestamps and GUIDs, the model itself is unstable, and dynamic values in HasData are the usual culprit.

Hardcode seed values, or better, move dynamic seeding into EF 9's UseSeeding/UseAsyncSeeding callbacks where it belongs. Save the warning suppression for upgrade bridges, and let CI catch pending model changes so this error never gets another chance to page you.

The full error reads: "The instance of entity type 'Order' cannot be tracked because another instance with the same key value for {'Id'} is already being tracked. When attaching existing entities, ensure that only one entity instance with a given key value is attached."

It shows up when a controller loads an entity for validation and then calls Update with a mapped DTO. Or when a test seeds data and the code under test attaches its own copy. Or in a background job that processes the same entity twice in one batch.

The reflexive fix is to scatter AsNoTracking until the error goes away. That works about as well as removing the battery from a smoke alarm. Here is what the error actually means and the fixes that address it.

What Does the Error Mean?

A DbContext enforces identity resolution: for a given entity type and key value, it tracks at most one instance. That is a feature. It is what lets EF Core figure out which row to update and guarantees that two queries for order 42 in the same context hand you the same object.

The error is EF Core telling you a second instance with the same key tried to enter the change tracker. Something earlier put instance A in the tracker, and now Attach, Update, or Add is bringing in instance B with the same key.

The important mental shift: the problem is never the line that throws. It is the earlier line that left instance A tracked. I covered how tracking works under the hood in understanding the EF Core change tracker.

The Classic Reproduction

Almost every occurrence reduces to this shape:

public async Task UpdateProduct(Guid id, ProductDto dto)
{
    // Instance A enters the change tracker
    var product = await context.Products.FirstAsync(p => p.Id == id);

    if (product.IsArchived)
    {
        throw new InvalidOperationException("Archived products are read-only.");
    }

    // Instance B: a different object, same key. Throws.
    var updated = dto.ToEntity(id);
    context.Products.Update(updated);

    await context.SaveChangesAsync();
}

FirstAsync tracked instance A. Update(updated) tries to track instance B with the same key. Collision.

Other common variants of the same disease:

• Repositories that load an aggregate for a check, then a service that attaches a mapper-produced copy.
• Seeding an entity in an integration test with the same context the handler uses.
• A long-lived context in a background job accumulating tracked entities across iterations until a duplicate arrives.

Fix 1: Update the Tracked Instance (the Right Default)

If the context already tracks the entity, do not attach a second copy. Copy the incoming values onto the tracked instance:

public async Task UpdateProduct(Guid id, ProductDto dto)
{
    var product = await context.Products.FirstAsync(p => p.Id == id);

    if (product.IsArchived)
    {
        throw new InvalidOperationException("Archived products are read-only.");
    }

    context.Entry(product).CurrentValues.SetValues(dto);

    await context.SaveChangesAsync();
}

CurrentValues.SetValues copies matching scalar properties from any object (entity, DTO, anonymous type) onto the tracked entity. Only properties that actually changed are marked modified, so the generated UPDATE touches only real changes. No second instance, no collision, and a smaller SQL statement than Update would produce.

For domain models with behavior, skip SetValues and call the entity's own methods (product.Rename(dto.Name)). Same principle: mutate the tracked instance instead of importing a rival.

Fix 2: Check the Tracker Before Attaching

Sometimes you receive a detached entity and legitimately do not know whether the context tracks a copy. Resolve through Local first:

public void Upsert(Product incoming)
{
    var tracked = context.Products.Local
        .FirstOrDefault(p => p.Id == incoming.Id);

    if (tracked is not null)
    {
        context.Entry(tracked).CurrentValues.SetValues(incoming);
    }
    else
    {
        context.Products.Update(incoming);
    }
}

Local looks only at the change tracker, no database round trip. This is the pattern for generic repository code where you cannot control what callers loaded earlier.

Fix 3: Stop Tracking What You Only Read

If the earlier load was purely for validation or display, it never needed tracking:

var product = await context.Products
    .AsNoTracking()
    .FirstAsync(p => p.Id == id);

This is the legitimate use of AsNoTracking: declaring that a read is a read. The anti-pattern is adding it reactively wherever the exception pops, which litters the codebase and eventually breaks a code path that relied on tracking. The distinction, plus what identity resolution does for you, is the subject of AsNoTracking and identity resolution.

Note that FindAsync is often the better tool for load-then-modify flows, since it returns the already-tracked instance when there is one instead of colliding with it. More on that in Find vs FirstOrDefault.

Fix 4: Clear the Tracker in Long-Lived Contexts

Batch jobs that reuse one context across thousands of iterations accumulate tracked entities. Eventually the same key comes around twice and throws. Between logical units of work, reset:

foreach (var batch in batches)
{
    await ProcessBatch(context, batch);
    await context.SaveChangesAsync();

    context.ChangeTracker.Clear();
}

ChangeTracker.Clear() detaches everything efficiently. It also caps memory growth, which matters as much as the exception in long-running processing. Better yet, create a short-lived context per batch with IDbContextFactory<T>, which also plays nicely with DbContext pooling.

The Fix That Is Not a Fix

You will find advice to set the entry state manually:

context.Entry(updated).State = EntityState.Modified;

This throws the same exception when a rival instance is tracked, so it is not even a workaround, and when it does work it marks every property modified, producing full-row updates. The same goes for disabling tracking globally with ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking: your updates keep working only until some code path expects tracked entities, and then you have a subtler bug than the one you started with.

Summary

"Cannot be tracked" means one context, one key, two objects. The context is right to refuse; identity resolution is what makes SaveChanges trustworthy.

Find the earlier load that left the first instance tracked. Then pick the fix that matches intent: copy values onto the tracked instance with SetValues (the right default for update endpoints), resolve through Local when you receive detached entities, use AsNoTracking for loads that were never going to save, and ChangeTracker.Clear() between batches in long-lived contexts.

If the error keeps reappearing across a codebase, the root cause is usually architectural: multiple layers each loading their own copy of the same aggregate. One load per unit of work, flowing through the call stack, makes the whole class of error disappear.

The first query your app sends through a DbContext is slow, and it has nothing to do with the database. Before EF Core can translate anything, it has to build the model: run OnModelCreating, apply every configuration, discover every entity, navigation, and index via reflection, and validate the result.

For a 20-entity model, that is noise. For a 300-entity model, it can be seconds of cold start, paid on the first request after every deploy, scale-out, or scale-from-zero wake-up. Compiled models move that entire cost to build time.

Where the Time Actually Goes

Model building happens once per model, lazily, on first use of the context. EF caches the result, so request two is fast; this is strictly a cold start tax.

The cost scales with model complexity: entity count, relationships, inheritance hierarchies, conventions to run over all of it. Microsoft's own benchmarks used a synthetic model with 449 entity types and 6,390 properties, where model preparation on first query took around 2 seconds, and a compiled model cut that phase by roughly 10x. In practice, under about 100 entities you will barely notice; past a couple hundred, the model build starts to dominate cold start ahead of even JIT and connection warmup.

Before optimizing, measure your own number. The cheapest way is logging around the first materialized query:

var stopwatch = Stopwatch.StartNew();

await using (var scope = app.Services.CreateAsyncScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    _ = db.Model; // forces the model build, nothing else
}

app.Logger.LogInformation(
    "Model build took {Elapsed} ms", stopwatch.ElapsedMilliseconds);

Accessing db.Model isolates model building from query compilation and database I/O, so you know exactly what a compiled model would buy you. If that number is 40 ms, close this tab and go optimize something real. If it is 900 ms and you run on scale-to-zero infrastructure, keep reading.

Generating a Compiled Model

The generator is part of the dotnet ef tooling:

dotnet tool update -g dotnet-ef

dotnet ef dbcontext optimize \
  --output-dir CompiledModels \
  --namespace MyApp.Infrastructure.CompiledModels

This runs your OnModelCreating once, at design time, and emits the finished model as C# source files into CompiledModels/. You will see one file per entity type plus an AppDbContextModel entry point. The files are large and generated; commit them, but exclude them from coverage and review noise.

Wire it up in your context options:

builder.Services.AddDbContext<AppDbContext>(options =>
    options
        .UseNpgsql(connectionString)
        .UseModel(MyApp.Infrastructure.CompiledModels.AppDbContextModel.Instance));

At startup, EF now loads the pregenerated model object instead of reflecting its way through your configuration. OnModelCreating simply never runs at runtime.

Two scope notes to set expectations:

• This affects model building only. Query translation, compilation, and execution are untouched. If your problem is slow queries, you want compiled queries and the usual query performance work, not compiled models. The names are similar, the features are unrelated.
• It combines well with the other cold start levers, ReadyToRun and trimming, because each one removes a different chunk of first-request latency.

The Restrictions That Decide Everything

Compiled models are not a free checkbox, and the limitations are not edge cases.

Global query filters are not supported. This is the big one. If your model calls HasQueryFilter anywhere, dotnet ef dbcontext optimize refuses to generate. And global query filters are load-bearing in a lot of real systems: they are the standard mechanism for soft delete and for multi-tenant row filtering.

Be careful with the failure mode here. The tool refusing at generation time is the good outcome. The dangerous path is a team that removes the filters to "make optimize work", or reworks them into repeating Where clauses that someone eventually forgets. A missing tenant filter is not a performance bug, it is a data leak. If query filters carry security semantics in the application, that limitation alone disqualifies compiled models until the filter can be expressed safely.

Lazy-loading and change-tracking proxies are not supported. UseLazyLoadingProxies and UseChangeTrackingProxies do not work with a compiled model. If you lean on lazy loading, that is a second disqualifier (and, separately, an invitation to revisit loading strategies).

Custom IModelCacheKeyFactory scenarios do not fit. The classic use is dynamic per-tenant model variation (different schemas per tenant, for example). A compiled model is one frozen model; "the model depends on runtime state" is the opposite of that.

The model is a snapshot, and it goes stale silently. Add a property, change a relationship, tweak a value conversion, and the compiled model keeps loading happily, describing the old model. EF does not detect the drift. The symptoms are downstream and confusing: missing columns in generated SQL, or a pending model changes error from migrations that seems to contradict the code in front of you.

Keeping the Snapshot Fresh

Staleness is a process problem, so fix it with process:

EF Core 9+: let MSBuild do it. The Microsoft.EntityFrameworkCore.Tasks package regenerates the compiled model during build:

dotnet add package Microsoft.EntityFrameworkCore.Tasks

<PropertyGroup>
  <EFOptimizeContext>true</EFOptimizeContext>
</PropertyGroup>

With that in place the snapshot can never drift from the code that produced it, which converts the worst limitation into a non-issue. If you are on EF 8 or earlier, the manual equivalent is a CI step: regenerate with dotnet ef dbcontext optimize and fail the build if git diff is non-empty. Never rely on humans remembering.

Also worth knowing: newer EF Core releases keep shaving time off model building itself, so re-measure on your current EF version before assuming you need this at all.

Who Should Actually Use This?

My decision list is short.

Good fit:

• Models in the hundreds of entity types, where the build cost is measured in seconds.
• Serverless and scale-to-zero deployments (Lambda, Azure Functions, Container Apps to zero) where cold start is a user-facing number you pay constantly.
• Modular systems with several large contexts, where each module pays its own model build. A modular monolith with 8 modules and 8 DbContexts multiplies this cost by 8.
• Pair it with dotnet ef dbcontext optimize running from CI so freshness is automatic.

Bad fit:

• Any model using HasQueryFilter for soft delete or tenancy. Hard stop until EF lifts the limitation.
• Lazy-loading proxy users.
• Small models. The complexity spend is real (generated code in the repo, a build step, one more thing to understand) and the win is milliseconds.
• Long-running services that restart weekly. You would be optimizing an event that happens 50 times a year.

Notice the shape: compiled models are a deployment-profile optimization, in the same family as Native AOT and R2R, not a general "make EF faster" switch. The steady state is untouched; only the first minute of process life improves.

Summary

• Model building is a one-time reflection cost on first DbContext use, and it scales with entity count: trivial at 20 entities, seconds at several hundred.
• dotnet ef dbcontext optimize plus UseModel moves that cost to build time, cutting the model preparation phase by roughly 10x on large models.
• The limitations are decisive, not cosmetic: no global query filters (so most soft delete and multi-tenant designs are out), no lazy-loading or change-tracking proxies, no dynamic per-tenant models.
• The snapshot goes stale silently. On EF 9+, turn on EFOptimizeContext so the build regenerates it; earlier, enforce regeneration in CI.
• Adopt it for big models on cold-start-sensitive infrastructure. Skip it everywhere else and measure db.Model build time before deciding.

Compiled models matter when model construction is a measured part of cold-start latency and add little value otherwise. One stopwatch line tells you which camp you are in.

You need an entity by its primary key. Two lines of EF Core do the job:

var order = await context.Orders.FindAsync(id);
var order = await context.Orders.FirstOrDefaultAsync(o => o.Id == id);

Most developers pick one by habit and never look back. But these two methods have genuinely different semantics, and the difference, whether the change tracker is consulted before the database, cuts both ways. In one codebase it is a free performance win. In another it lets a background job keep processing state that the database has already changed.

How FindAsync Works

FindAsync runs in two phases:

1. Change tracker lookup. If an entity of that type with that key is already tracked, return it. No SQL, no round trip, nanoseconds.
2. Database query. On a miss, execute a SELECT ... WHERE pk = @p, track the result, return it (or null).

You can see phase 1 in isolation:

var first = await context.Orders.FindAsync(id);   // SQL query
var second = await context.Orders.FindAsync(id);  // no SQL, same instance

Console.WriteLine(ReferenceEquals(first, second)); // True

Phase 1 also covers entities that were added but not yet saved:

var draft = new Order { Id = id, Status = OrderStatus.Draft };
context.Orders.Add(draft);

var found = await context.Orders.FindAsync(id); // returns draft, no SQL

That behavior is unique to Find. A FirstOrDefaultAsync before SaveChanges queries the database, does not see the pending insert, and returns null. If your unit of work creates an entity and a later step in the same request needs to fetch it, Find is the only lookup that behaves consistently.

For composite keys, pass the values in the order the key was declared, a detail I covered in composite primary keys:

var item = await context.OrderItems.FindAsync(orderId, productId);

The CancellationToken Trap

That composite-key overload hides the one genuine footgun in the Find API. FindAsync takes its key values as params object?[], so this compiles and looks completely reasonable:

// Wrong: the token is absorbed as a second key value
var order = await context.Orders.FindAsync(id, cancellationToken);

The compiler binds it to the params overload, treats the token as another key component, and EF throws at runtime:

"Entity type 'Order' is defined with a single key property, but 2 values were passed to the 'Find' method."

To pass a cancellation token, wrap the key values in an array so the call binds to the FindAsync(object?[] keyValues, CancellationToken cancellationToken) overload:

var order = await context.Orders.FindAsync([id], cancellationToken);

[id] is a C# 12 collection expression; on older language versions, write new object[] { id } instead. FirstOrDefaultAsync(predicate, cancellationToken) has no such trap, which is one quiet reason some codebases standardize on it. Do not let that decide the choice; just know the array form and move on.

How FirstOrDefaultAsync Works

FirstOrDefaultAsync is just a LINQ query. It always generates SQL, always hits the database, and gives you the full query pipeline:

var order = await context.Orders
    .Include(o => o.Items)
    .FirstOrDefaultAsync(o => o.Id == id);

Everything Find cannot do lives here:

• Includes. Find has no way to load related data; you would follow up with explicit loading.
• No-tracking reads. AsNoTracking only exists on queries.
• Projections. Selecting a DTO instead of the entity, usually the fastest read of all, is query-only.
• Any predicate. Lookups by anything other than the primary key.
• Query filters. FirstOrDefault respects global query filters. Find bypasses them when it hits the tracker, and applies them on the database path, which can produce genuinely confusing mixed behavior in soft-delete and multi-tenant setups.

The Cache Hit That Becomes a Stale Read

The change tracker consultation is a per-context cache with no expiration and no invalidation. Within a short-lived request context, that is pure upside. In anything long-lived, it is a stale-data machine:

// Background job, one context per batch run
var order = await context.Orders.FindAsync(orderId); // loads Status = Submitted

// meanwhile, a user cancels the order; another context saves Status = Cancelled

// ...later in the same batch:
var again = await context.Orders.FindAsync(orderId); // still Submitted, no SQL

The second call never asks the database, so it cannot see the cancellation. The fix is either a context per unit of work (my strong preference, same reasoning as in DbContext pooling), an explicit reload when freshness matters:

await context.Entry(order).ReloadAsync();

or clearing the tracker between batches with ChangeTracker.Clear().

Here is the part that surprises even experienced EF users: switching to FirstOrDefaultAsync does not fully fix stale reads on tracked entities. A tracking query executes the SQL, but identity resolution then discards the fresh values for any entity already in the tracker and returns the existing instance, preserving your unsaved changes. The database was consulted; the object you got back still holds the old (or locally modified) values. I dug into that mechanism in AsNoTracking and identity resolution. If you need guaranteed-fresh values in the same context, ReloadAsync or a no-tracking query are the honest options.

Performance: What the Difference Is Worth

On a tracker hit, Find costs a dictionary lookup. A FirstOrDefault for the same entity costs a full round trip: SQL generation (cached), network, parse, execution, materialization. Even against a local database that is a few hundred microseconds versus effectively zero.

On a tracker miss, both run a nearly identical primary-key SELECT, and the difference is noise.

So the performance case for Find is entirely about repeated access within one context: request pipelines where validation, authorization, and the handler each resolve the same aggregate, or graph-fixing code that touches the same parents repeatedly. Those patterns get the repeat lookups for free. If your code loads each entity exactly once per request, choose by capability, not speed, and spend your optimization budget where it counts, on the issues in EF Core query performance mistakes.

Side-by-Side Comparison

The two methods, dimension by dimension:

My Decision Rules

• Load-then-modify by primary key: FindAsync. It composes with pending adds, returns the tracked instance instead of colliding with it (the error I dissected in fixing the "cannot be tracked" error), and repeated calls are free.
• Read-only display or list data: a projection with AsNoTracking, via FirstOrDefaultAsync or ToListAsync. Never Find; you do not want tracking at all.
• Need related data: FirstOrDefaultAsync with Include, or better, a projection shaped for the use case.
• Soft delete or multi-tenancy in play: prefer queries, so filters apply uniformly.
• Long-lived context: prefer queries plus explicit reloads, or restructure to short-lived contexts and keep using Find safely.

One naming note: SingleOrDefaultAsync versus FirstOrDefaultAsync on a primary key predicate makes no practical difference, the key is unique, but Single queries with LIMIT 2 to assert uniqueness while First stops at one row and reads as intent here.

Summary

FindAsync is a primary-key lookup with a built-in L1 cache: the change tracker. FirstOrDefaultAsync is a real query with the full pipeline: predicates, includes, no-tracking, projections, and query filters.

The tracker check is the whole story. It makes Find the right default for load-then-modify work in short-lived contexts, where repeat lookups are free and pending adds are visible. It makes Find a liability in long-lived contexts, where it happily serves data the database moved past minutes ago.

And remember the twist: a tracking FirstOrDefault does not rescue you from staleness on already-tracked entities, because identity resolution keeps the old instance. When freshness is a requirement, say it in code: ReloadAsync, AsNoTracking, or a fresh context.

Every request in a typical ASP.NET Core app constructs a DbContext, uses it for a handful of queries, and throws it away. Construction is not free: EF Core sets up the change tracker, the service scope, and per-instance state, and disposal tears it down.

AddDbContextPool skips that churn by recycling instances. On paper it is a one-word change. In practice it changes the lifecycle rules of your context, and code that was fine with AddDbContext can start leaking state across requests.

Here is what pooling actually buys you, and the three ways it bites.

What Pooling Changes

The registration looks almost identical:

builder.Services.AddDbContextPool<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Database")));

With plain AddDbContext, each scope constructs a new context and disposes it at scope end. With pooling, "dispose" becomes "reset and return to pool", and "construct" becomes "rent from pool if one is available".

The reset clears EF Core's internal state: the change tracker is emptied, connection state is handled, and the context is as good as new from EF Core's perspective. That last qualifier is where the problems live.

The default pool size is 1024. Under burst load beyond that, extra contexts are created and simply disposed instead of pooled, so the pool never becomes a bottleneck or a queue. You can tune it with the second argument to AddDbContextPool, but change the default only after measuring pool saturation and allocation pressure.

Do not confuse context pooling with connection pooling. ADO.NET connection pooling happens a layer below and is always on; a non-pooled context still reuses pooled database connections. For the Npgsql side of that story, see NpgsqlDataSource and connection pooling.

Is DbContext Pooling Worth It?

Pooling removes per-request allocation and setup of the context graph. The EF team's own benchmarks show it matters most when the work per context is tiny: high-RPS endpoints running one cheap indexed query. In those scenarios the requests-per-second improvement is material, but the result depends on how much work surrounds each context.

In a typical business app, the database round trip costs a few milliseconds and dominates the microseconds saved on construction. There, pooling is a rounding error.

My rule: pooling is a legitimate optimization for hot, simple endpoints, and harmless elsewhere if your context is stateless. Measure with BenchmarkDotNet or a load test before crediting it with anything.

Bite 1: State on the Context Leaks Across Requests

This is the big one. The pool resets what EF Core knows about, and nothing else. Any field you added to your DbContext subclass survives into the next request:

public class AppDbContext(DbContextOptions<AppDbContext> options)
    : DbContext(options)
{
    // DANGER with pooling: this survives the reset
    public Guid TenantId { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>()
            .HasQueryFilter(o => o.TenantId == TenantId);
    }
}

With AddDbContext, this pattern works: each request gets a fresh context, middleware sets TenantId, the global query filter does its job. With AddDbContextPool, request B rents the context request A used. If B's middleware fails to set TenantId, B silently queries A's tenant data. That is not a performance bug, that is a data breach.

If you pool a stateful context, the state must be set unconditionally on every rental. And because a pooled context cannot inject scoped services (the next bite), the assignment has to happen after the rental. The safe pattern is middleware that resolves the scoped context, which rents it from the pool, and assigns the value before any handler runs a query:

// Middleware, runs on every request without exception
app.Use(async (httpContext, next) =>
{
    var db = httpContext.RequestServices
        .GetRequiredService<AppDbContext>();

    // Always assign, even when the request has no tenant
    db.TenantId = ResolveTenant(httpContext);

    await next();
});

Multi-tenancy is the most common place this trap appears, and the tenant-per-request patterns from multi-tenant applications with EF Core need this exact adjustment before they are pool-safe.

Bite 2: The Constructor Contract

A pooled context must expose a single public constructor that takes only DbContextOptions<T>. The pool constructs instances itself, outside any request scope, so it cannot satisfy other dependencies:

// Works with AddDbContext, throws at startup with AddDbContextPool
public class AppDbContext(
    DbContextOptions<AppDbContext> options,
    ICurrentUser currentUser) : DbContext(options)
{
}

If your context injects the current user for audit logging, or a tenant service, pooling forces a redesign: move the dependency out of the constructor and into an interceptor resolved from DI, or set it post-rental as shown above. Interceptors registered via options.AddInterceptors in the pooled options are shared singletons, so they must be stateless too.

Bite 3: Long-Lived Rentals Poison the Pool

The pool assumes short rentals. A context held for the length of a background job, or one that tracked ten thousand entities, gets its change tracker cleared on return, but the internal structures may have grown, and while it is held, it is not available.

Two related mistakes:

• Injecting a pooled context into a singleton hosted service. The context is rented once and never returned. Use IDbContextFactory<T> instead, and there is a pooled variant:

builder.Services.AddPooledDbContextFactory<AppDbContext>(options =>
    options.UseNpgsql(connectionString));

public class OrderSyncJob(IDbContextFactory<AppDbContext> factory)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            await using var context = await factory.CreateDbContextAsync(ct);
            // short-lived unit of work, context returns to pool on dispose
        }
    }
}

• Treating the pooled context as a cache because "it sticks around". The change tracker is wiped on every return. Anything you hoped would persist will not, and anything you did not expect to persist (your own fields) will. It is exactly backwards from what intuition suggests.

My Recommendation

• Context has no custom state and no request-varying dependencies: pooling is low risk, but still measure it on the target workload.
• Context carries per-request state (tenant, user, soft-delete toggles): pool only after making the assignment unconditional on every rental, and add a test that hammers two tenants concurrently and asserts isolation.
• Background services: AddPooledDbContextFactory, one context per unit of work.
• Low-traffic apps: skip it. The complexity is real and the win is not.

More context lifetime guidance lives in DbContext configuration best practices.

Summary

AddDbContextPool recycles context instances, trading construction cost for stricter lifecycle rules. The pool resets EF Core's state, not yours: custom fields survive across requests, constructors are limited to options-only, and singletons that hold a rental starve the pool.

The performance win is real but narrow, concentrated in hot endpoints where per-request query work is tiny. The failure mode is not narrow at all: leaked tenant or user state on a reused context is a correctness bug that only shows up under concurrent load.

Pool stateless contexts freely. Pool stateful ones only after making the state impossible to forget.

AsNoTracking is probably the most repeated EF Core performance tip on the internet, and it is good advice. I give it myself.

But it has a side effect that almost nobody mentions. Query 100 orders with their customer, where all 100 belong to the same customer, and you get 100 separate Customer objects in memory. Same key, same data, 100 instances. There is a third query mode that fixes exactly this, and knowing when to reach for it is the point of this article.

The Three Query Modes

Every EF Core query runs in one of three modes:

Tracking (the default). Every materialized entity is registered in the change tracker with a snapshot of its original values. That is what makes SaveChanges work, and it is also why the change tracker maintains an identity map: one instance per key, guaranteed. Read the same row twice, get the same object reference.

No tracking.

var orders = await dbContext.Orders
    .Include(o => o.Customer)
    .AsNoTracking()
    .ToListAsync();

No snapshots, no change tracker entries, no identity map. EF materializes a fresh object for whatever each row says, hands it to you, and forgets it existed. This is the right default for read-only queries, and you will find it in every EF Core performance guide for good reason.

No tracking with identity resolution.

var orders = await dbContext.Orders
    .Include(o => o.Customer)
    .AsNoTrackingWithIdentityResolution()
    .ToListAsync();

Still untracked, still read-only. But during materialization, EF keeps a temporary identity map: the first time it sees Customer 42 it creates the instance, and every subsequent row with CustomerId = 42 gets a reference to that same instance. The map is thrown away when the query completes.

Seeing the Duplication

The behavior difference is easiest to see with reference equality. Take 100 orders that all belong to one customer:

// Plain AsNoTracking
var orders = await dbContext.Orders
    .Where(o => o.CustomerId == customerId)
    .Include(o => o.Customer)
    .AsNoTracking()
    .ToListAsync();

var distinctInstances = orders
    .Select(o => o.Customer)
    .Distinct(ReferenceEqualityComparer.Instance)
    .Count();

Console.WriteLine(distinctInstances); // 100

One hundred Customer objects, all with the same primary key, all carrying identical copies of every column. Swap in AsNoTrackingWithIdentityResolution and the same code prints 1.

To be precise about what is duplicated: this is not 100 customer rows coming over the wire in this shape (the JOIN repeats customer columns per row either way, that part is inherent to SQL). The duplication is in materialization: 100 allocated objects instead of 1, and 100x the memory for that entity's data.

If the customer row is wide (a JSON column, a description, a byte array), the memory multiplication gets serious. 1,000 rows sharing 10 customers with 2 KB of customer data each: tracking or identity resolution holds 20 KB of customer data, plain AsNoTracking holds 2 MB.

When Do the Duplicates Actually Hurt?

Most of the time, duplicated instances are harmless. You map the rows to a DTO, serialize, respond, and the garbage collector cleans up. That is why plain AsNoTracking is still the right default.

The duplication bites in three specific situations:

1. In-memory graph processing. Any logic that assumes "same entity means same object" breaks quietly. Grouping by reference, building lookups keyed by instance, walking the object graph and mutating shared nodes: with plain no-tracking, "shared" nodes are not shared, so you update one copy of the customer and the other 99 still show the old value.

2. Memory-heavy read paths. Reporting queries with wide shared parents, exports, or anything that holds large result sets alive while processing. Here the duplication is a real allocation and GC cost, not a rounding error.

3. Cyclic or diamond-shaped Includes. Multiple include paths reaching the same entity produce independent copies of it. Serializers configured with reference preservation then see distinct objects instead of one, and payload sizes balloon.

Notice what all three have in common: you are treating the result as a graph, not as rows. That is the heuristic. Rows to DTOs: AsNoTracking. A graph you will traverse: identity resolution (or projection, more on that below).

What Identity Resolution Costs

Nothing is free. AsNoTrackingWithIdentityResolution maintains a dictionary of materialized keys for the duration of the query, so it pays lookup and bookkeeping CPU per row, plus the map itself.

The expected cost profile is:

• AsNoTracking: fastest, most allocations when parents are shared.
• AsNoTrackingWithIdentityResolution: slightly slower per row, but allocations drop as sharing grows.
• Tracking: the expensive one, because snapshots and change tracker registration dwarf the identity map cost.

The break-even depends on the share ratio. With no shared entities at all (every order has a distinct customer), the identity map is pure overhead: skip it. With high sharing, the reduced allocations can pay the CPU back, and the semantic correctness comes free. Benchmark the actual query instead of treating general ratios as a guarantee.

Here is how the two modes compare, dimension by dimension:

Setting a Default (and Overriding It)

You can make no-tracking the context-wide default, which I do for read-heavy applications and in the query side of CQRS:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString)
        .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));

QueryTrackingBehavior.NoTrackingWithIdentityResolution is also valid as a default, but it pays the identity-map cost on every query to fix a problem many queries do not have. Set NoTracking as the default and opt up per query:

// Read model: default no-tracking applies.
var summaries = await dbContext.Orders
    .Select(o => new OrderSummary(o.Id, o.Customer.Name, o.Total))
    .ToListAsync();

// Graph-shaped read: opt into identity resolution.
var graph = await dbContext.Orders
    .Include(o => o.Customer)
    .Include(o => o.Lines).ThenInclude(l => l.Product)
    .AsNoTrackingWithIdentityResolution()
    .ToListAsync();

// Command: opt back into tracking to modify.
var order = await dbContext.Orders
    .AsTracking()
    .FirstAsync(o => o.Id == orderId);

One warning for the no-tracking-by-default setup: it is the classic source of "I changed the entity and SaveChanges did nothing". If updates silently stop working after you flip the default, that is why, and it is a cousin of the already-tracked errors you get when mixing modes carelessly.

The Option That Beats Both: Projection

Before choosing between the two no-tracking flavors, ask whether you need entities at all.

var report = await dbContext.Orders
    .Where(o => o.CreatedAt >= from)
    .Select(o => new OrderReportRow(
        o.Id,
        o.Customer.Name,
        o.Lines.Sum(l => l.Quantity * l.UnitPrice)))
    .ToListAsync();

A Select into a DTO sidesteps the entire question: nothing is tracked, nothing is duplicated, only the needed columns cross the wire, and the identity map never enters the picture. Projections do not need AsNoTracking at all, because there are no entities to track. For pure read endpoints this wins on every axis, and skipping it is one of the EF Core query mistakes I see most often. The same materialization behavior also underlies query splitting decisions: how EF turns rows into objects is worth understanding once, deeply.

Entities (and therefore this article's choice) remain relevant when you genuinely want the object graph: domain-shaped reads, mappers that consume entities, or code paths shared with tracking scenarios.

Summary

• AsNoTracking skips the change tracker AND the identity map. Every row materializes a fresh instance, so shared parents are duplicated: 100 orders with one customer means 100 Customer objects.
• AsNoTrackingWithIdentityResolution keeps queries untracked but deduplicates by key during materialization, at the price of a per-query identity map.
• Decide by shape: rows (map to DTO and return) take plain AsNoTracking; graphs (traverse, group, serialize with references) take identity resolution.
• Set NoTracking as the context default for read-heavy apps, opt into AsTracking for commands, and reach for identity resolution explicitly where sharing matters.
• The best version of a read query is often a projection, which makes the whole dilemma disappear.

The tip "use AsNoTracking for reads" is useful but incomplete. The missing piece is knowing that the identity map was doing quiet work for you, and knowing the one-line fix when its absence shows.

An API that returns an unbounded collection has a performance bug waiting for enough data.

Why Pagination Matters

Imagine a query returning 100,000 orders. Without pagination, you're loading all of them into memory, serializing to JSON, and sending over the network. Your API response is slow, your server memory spikes, and your users wait.

Pagination loads a small subset at a time - 20 records per page instead of 100,000. Unbounded queries are one of the most common EF Core query performance mistakes, and pagination is the fix.

Offset Pagination

The most common approach. Use Skip and Take:

app.MapGet("/api/orders", async (
    ApplicationDbContext db,
    int page = 1,
    int pageSize = 20) =>
{
    if (page < 1) page = 1;
    if (pageSize < 1) pageSize = 20;
    if (pageSize > 100) pageSize = 100; // Prevent abuse

    var totalCount = await db.Orders.CountAsync();

    var orders = await db.Orders
        .OrderByDescending(o => o.CreatedAt)
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(o => new OrderResponse(
            o.Id,
            o.Status.ToString(),
            o.TotalAmount,
            o.CreatedAt))
        .ToListAsync();

    return new PagedResponse<OrderResponse>(
        orders,
        page,
        pageSize,
        totalCount);
});

The response wrapper:

public sealed record PagedResponse<T>(
    List<T> Items,
    int Page,
    int PageSize,
    int TotalCount)
{
    public int TotalPages => (int)Math.Ceiling(TotalCount / (double)PageSize);
    public bool HasNextPage => Page < TotalPages;
    public bool HasPreviousPage => Page > 1;
}

public sealed record OrderResponse(
    Guid Id,
    string Status,
    decimal TotalAmount,
    DateTime CreatedAt);

Generated SQL:

SELECT o."Id", o."Status", o."TotalAmount", o."CreatedAt"
FROM "Orders" AS o
ORDER BY o."CreatedAt" DESC
LIMIT @take OFFSET @skip;

The Problem With Offset Pagination

Offset pagination has a scaling issue. OFFSET 50000 means the database must scan and discard 50,000 rows before returning the next 20. The deeper you paginate, the slower it gets.

There's a second, sneakier issue: COUNT(*) runs on every request. On a large filtered table, the count query can cost more than fetching the page. If the UI doesn't display total pages, skip the count.

Keyset Pagination (Cursor-Based)

Keyset pagination uses the last seen value as a cursor. I did a deep dive on why this is so fast in understanding cursor pagination.

app.MapGet("/api/orders", async (
    ApplicationDbContext db,
    DateTime? cursor,
    int pageSize = 20) =>
{
    if (pageSize < 1) pageSize = 20;
    if (pageSize > 100) pageSize = 100;

    IQueryable<Order> query = db.Orders;

    if (cursor.HasValue)
    {
        query = query.Where(o => o.CreatedAt < cursor.Value);
    }

    var orders = await query
        .OrderByDescending(o => o.CreatedAt)
        .Take(pageSize + 1) // Take one extra to check for next page
        .Select(o => new OrderResponse(
            o.Id,
            o.Status.ToString(),
            o.TotalAmount,
            o.CreatedAt))
        .ToListAsync();

    var hasNextPage = orders.Count > pageSize;
    if (hasNextPage)
    {
        orders.RemoveAt(orders.Count - 1);
    }

    var nextCursor = orders.LastOrDefault()?.CreatedAt;

    return new CursorPagedResponse<OrderResponse>(
        orders, nextCursor, hasNextPage);
});

public sealed record CursorPagedResponse<T>(
    List<T> Items,
    DateTime? NextCursor,
    bool HasNextPage);

Generated SQL:

SELECT o."Id", o."Status", o."TotalAmount", o."CreatedAt"
FROM "Orders" AS o
WHERE o."CreatedAt" < @cursor
ORDER BY o."CreatedAt" DESC
LIMIT @take;

No OFFSET. The database uses the index to jump directly to the cursor position. Performance is constant regardless of how deep you paginate. One provider note: with Npgsql, timestamp columns map to timestamptz by default, and parameter values must have DateTimeKind.Utc, so convert incoming cursor values with DateTime.SpecifyKind if they arrive unspecified.

Compound Cursors

When multiple rows can have the same CreatedAt, use a compound cursor:

app.MapGet("/api/orders", async (
    ApplicationDbContext db,
    DateTime? cursorDate,
    Guid? cursorId,
    int pageSize = 20) =>
{
    IQueryable<Order> query = db.Orders;

    if (cursorDate.HasValue && cursorId.HasValue)
    {
        query = query.Where(o =>
            o.CreatedAt < cursorDate.Value ||
            (o.CreatedAt == cursorDate.Value &&
             o.Id < cursorId.Value));
    }

    var orders = await query
        .OrderByDescending(o => o.CreatedAt)
        .ThenByDescending(o => o.Id)
        .Take(pageSize + 1)
        .Select(o => new OrderResponse(
            o.Id, o.Status.ToString(), o.TotalAmount, o.CreatedAt))
        .ToListAsync();

    var hasNextPage = orders.Count > pageSize;
    if (hasNextPage) orders.RemoveAt(orders.Count - 1);

    var last = orders.LastOrDefault();

    return new
    {
        Items = orders,
        NextCursorDate = last?.CreatedAt,
        NextCursorId = last?.Id,
        HasNextPage = hasNextPage
    };
});

Guid has comparison operators since .NET 7, and EF Core translates o.Id < cursorId.Value into a plain SQL comparison. Back it with a composite index on (CreatedAt, Id) so the whole predicate stays an index seek.

Extracting a Reusable Pagination Extension

public static class PaginationExtensions
{
    public static async Task<PagedResponse<T>> ToPagedListAsync<T>(
        this IQueryable<T> query,
        int page,
        int pageSize,
        CancellationToken ct = default)
    {
        var totalCount = await query.CountAsync(ct);

        var items = await query
            .Skip((page - 1) * pageSize)
            .Take(pageSize)
            .ToListAsync(ct);

        return new PagedResponse<T>(items, page, pageSize, totalCount);
    }
}

Usage:

var result = await db.Orders
    .OrderByDescending(o => o.CreatedAt)
    .Select(o => new OrderResponse(
        o.Id, o.Status.ToString(), o.TotalAmount, o.CreatedAt))
    .ToPagedListAsync(page, pageSize, ct);

Filtering + Pagination

Always apply filters before pagination:

app.MapGet("/api/orders", async (
    ApplicationDbContext db,
    OrderStatus? status,
    DateTime? fromDate,
    int page = 1,
    int pageSize = 20) =>
{
    var query = db.Orders.AsQueryable();

    if (status.HasValue)
        query = query.Where(o => o.Status == status.Value);

    if (fromDate.HasValue)
        query = query.Where(o => o.CreatedAt >= fromDate.Value);

    return await query
        .OrderByDescending(o => o.CreatedAt)
        .Select(o => new OrderResponse(
            o.Id, o.Status.ToString(), o.TotalAmount, o.CreatedAt))
        .ToPagedListAsync(page, pageSize);
});

Index Requirements

Pagination queries need proper indexes:

// EF Core index configuration
public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        // Index for ordering + pagination
        builder.HasIndex(o => o.CreatedAt)
               .IsDescending();

        // Composite index for filtered pagination
        builder.HasIndex(o => new { o.Status, o.CreatedAt })
               .IsDescending(false, true);
    }
}

Without these indexes, the database does a full table scan for every page request.

Offset vs Keyset - When to Use Each

• Jumping to an arbitrary page: only offset can do it; keyset moves strictly forward (and optionally backward)
• Performance at depth: offset degrades linearly; keyset stays constant
• Implementation effort: offset is a few lines; keyset needs cursors and tiebreakers
• Stability under concurrent inserts: offset pages shift when rows are added; keyset pages don't skip or duplicate rows
• Best fit: offset for admin UIs and small datasets; keyset for public APIs, infinite scroll, and large datasets

Use offset pagination for admin pages where users need "go to page 5". Use keyset pagination for public APIs and infinite scroll feeds. Pagination design is one of the topics I cover end to end in Pragmatic REST APIs.

Summary

Cap every collection response and apply filters before pagination. Offset pagination is appropriate when random page numbers matter and the result set stays modest. For deep or continuously changing feeds, use a unique, stable ordering and a matching index to build a keyset cursor.

The LINQ expression is not what your database executes. Generated SQL reveals accidental joins, missing predicates, parameter values, and repeated queries that are invisible at the C# level. EF Core gives you lightweight inspection for development and structured diagnostics for production.

Why You Need to See the SQL

SQL logging in EF Core means routing the commands the provider sends to the database, and optionally their parameter values, into a log you can read.

EF Core generates SQL behind the scenes. Most of the time it's fine, but sometimes it generates queries that are inefficient, missing indexes, or drastically different from what you expected. If you're not looking at the SQL, you're flying blind.

Check generated SQL during development, especially for complex LINQ queries. The log output exposes N+1 problems, unnecessary subqueries, and missing WHERE clauses that are easy to miss in C#. Understanding what EF Core produces is essential for EF Core performance optimization.

Built-in Logging

The simplest approach - configure EF Core to log SQL to the console or your logging framework:

builder.Services.AddDbContext<AppDbContext>(options =>
{
    options.UseNpgsql(connectionString)
           .LogTo(Console.WriteLine, LogLevel.Information)
           .EnableSensitiveDataLogging()
           .EnableDetailedErrors();
});

• LogTo(Console.WriteLine): Sends all EF Core log messages to the console
• EnableSensitiveDataLogging(): Shows parameter values in logs (disable in production!)
• EnableDetailedErrors(): Includes more context in error messages

To filter only SQL queries:

options.LogTo(
    Console.WriteLine,
    new[] { DbLoggerCategory.Database.Command.Name },
    LogLevel.Information);

This outputs something like:

Executed DbCommand (5ms) [Parameters=[@__id_0='?' (DbType = Guid)],
CommandType='Text', CommandTimeout='30']
SELECT p."Id", p."Name", p."Price"
FROM "Products" AS p
WHERE p."Id" = @__id_0

Using ILoggerFactory

For better integration with ASP.NET Core's logging:

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();

    options.UseNpgsql(connectionString)
           .UseLoggerFactory(loggerFactory);
});

Then configure the log level in appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.EntityFrameworkCore.Database.Command": "Information",
      "Microsoft.EntityFrameworkCore.Infrastructure": "Warning"
    }
  }
}

This lets you control EF Core logging granularity through configuration.

ToQueryString() for Ad-Hoc Inspection

During debugging, you can convert any LINQ query to its SQL representation without executing it:

var query = dbContext.Products
    .Where(p => p.Price > 100)
    .OrderBy(p => p.Name)
    .Take(10);

var sql = query.ToQueryString();
Console.WriteLine(sql);

// Output:
// SELECT p."Id", p."Name", p."Price"
// FROM "Products" AS p
// WHERE p."Price" > 100.0
// ORDER BY p."Name"
// LIMIT 10

This is useful for checking query shape before execution and in provider-backed tests that verify LINQ-to-SQL translation.

Query Tags

Add descriptive tags to queries so you can identify them in logs and database monitoring tools:

var products = await dbContext.Products
    .TagWith("GetPopularProducts - called from DashboardController")
    .Where(p => p.OrderCount > 100)
    .OrderByDescending(p => p.OrderCount)
    .Take(20)
    .ToListAsync();

The generated SQL includes the tag as a comment:

-- GetPopularProducts - called from DashboardController

SELECT p."Id", p."Name", p."OrderCount"
FROM "Products" AS p
WHERE p."OrderCount" > 100
ORDER BY p."OrderCount" DESC
LIMIT 20

This makes it trivial to trace slow queries back to their source code. In pg_stat_activity, slow query logs, or your database monitoring tool, you'll see the comment right alongside the query.

Interceptors for Advanced Logging

Use interceptors for fine-grained control over query logging:

public class QueryLoggingInterceptor : DbCommandInterceptor
{
    private readonly ILogger<QueryLoggingInterceptor> _logger;

    public QueryLoggingInterceptor(ILogger<QueryLoggingInterceptor> logger)
    {
        _logger = logger;
    }

    public override ValueTask<InterceptionResult<DbDataReader>> ReaderExecutingAsync(
        DbCommand command,
        CommandEventData eventData,
        InterceptionResult<DbDataReader> result,
        CancellationToken cancellationToken = default)
    {
        _logger.LogDebug("Executing query:\n{Sql}", command.CommandText);
        return base.ReaderExecutingAsync(command, eventData, result, cancellationToken);
    }

    public override ValueTask<DbDataReader> ReaderExecutedAsync(
        DbCommand command,
        CommandExecutedEventData eventData,
        DbDataReader result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Duration.TotalMilliseconds > 500)
        {
            _logger.LogWarning(
                "Slow query detected ({Duration}ms):\n{Sql}",
                eventData.Duration.TotalMilliseconds,
                command.CommandText);
        }

        return base.ReaderExecutedAsync(command, eventData, result, cancellationToken);
    }
}

Register the interceptor:

builder.Services.AddSingleton<QueryLoggingInterceptor>();

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    var interceptor = sp.GetRequiredService<QueryLoggingInterceptor>();

    options.UseNpgsql(connectionString)
           .AddInterceptors(interceptor);
});

Detecting N+1 Queries

N+1 queries are the most common of the EF Core query performance mistakes. An interceptor can detect them (register it as scoped so the counter is per request):

public class NPlus1DetectorInterceptor : DbCommandInterceptor
{
    private readonly ILogger<NPlus1DetectorInterceptor> _logger;
    private int _queryCount;
    private string? _currentEndpoint;

    public NPlus1DetectorInterceptor(
        ILogger<NPlus1DetectorInterceptor> logger)
    {
        _logger = logger;
    }

    public void ResetForRequest(string endpoint)
    {
        _queryCount = 0;
        _currentEndpoint = endpoint;
    }

    public override ValueTask<DbDataReader> ReaderExecutedAsync(
        DbCommand command,
        CommandExecutedEventData eventData,
        DbDataReader result,
        CancellationToken cancellationToken = default)
    {
        _queryCount++;

        if (_queryCount > 10)
        {
            _logger.LogWarning(
                "Potential N+1 detected: {Count} queries for {Endpoint}.\n" +
                "Latest query:\n{Sql}",
                _queryCount, _currentEndpoint, command.CommandText);
        }

        return base.ReaderExecutedAsync(command, eventData, result, cancellationToken);
    }
}

Using MiniProfiler

MiniProfiler gives you a visual SQL profiler in your browser:

dotnet add package MiniProfiler.AspNetCore.Mvc
dotnet add package MiniProfiler.EntityFrameworkCore

Configure it:

builder.Services.AddMiniProfiler(options =>
{
    options.RouteBasePath = "/profiler";
}).AddEntityFramework();

app.UseMiniProfiler();

Navigate to /profiler/results-index to see:

• Every SQL query executed per request
• Query duration
• Duplicate query detection
• Parameter values

This is my go-to tool during development for spotting performance issues.

Structured Logging for Production

In production, log query metrics without the full SQL:

public class ProductionQueryInterceptor : DbCommandInterceptor
{
    private readonly ILogger<ProductionQueryInterceptor> _logger;

    public ProductionQueryInterceptor(
        ILogger<ProductionQueryInterceptor> logger)
    {
        _logger = logger;
    }

    public override ValueTask<DbDataReader> ReaderExecutedAsync(
        DbCommand command,
        CommandExecutedEventData eventData,
        DbDataReader result,
        CancellationToken cancellationToken = default)
    {
        _logger.LogInformation(
            "Query executed. Duration: {DurationMs}ms, " +
            "CommandType: {CommandType}, " +
            "HasParameters: {HasParameters}",
            eventData.Duration.TotalMilliseconds,
            command.CommandType,
            command.Parameters.Count > 0);

        return base.ReaderExecutedAsync(
            command, eventData, result, cancellationToken);
    }
}

Never log full SQL with parameter values in production - it may contain sensitive data. Log metrics only.

Debug View in Tests

For integration tests, capture generated SQL:

[Fact]
public async Task GetProducts_GeneratesExpectedSql()
{
    var queries = new List<string>();

    var options = new DbContextOptionsBuilder<AppDbContext>()
        .UseNpgsql(_connectionString)
        .LogTo(sql =>
        {
            if (sql.Contains("SELECT") || sql.Contains("INSERT"))
            {
                queries.Add(sql);
            }
        }, LogLevel.Information)
        .Options;

    await using var context = new AppDbContext(options);

    var products = await context.Products
        .Where(p => p.IsActive)
        .ToListAsync();

    queries.Should().HaveCount(1);
    queries[0].Should().Contain("\"IsActive\"");
}

Summary

Use ToQueryString and development logging to understand query shape before performance becomes an incident. Use query tags and interceptors to connect slow commands to application operations. Keep sensitive-data logging out of production and prefer duration, command metadata, and sanitized diagnostics over parameter values.

SaveChanges looks simple because the change tracker is doing the difficult work behind it. Understanding that machinery makes tracking bugs and unnecessary memory use much easier to diagnose.

How Does the Change Tracker Work?

When you query data through a DbContext, EF Core doesn't just return objects - it tracks them. Every entity loaded from the database goes into the change tracker with its original property values stored as a snapshot.

When you call SaveChangesAsync, EF Core compares the current values to the original snapshot. If anything changed, it generates an UPDATE statement with only the modified columns.

Entity States

Every tracked entity is in one of five states:

var entry = context.Entry(order);
Console.WriteLine(entry.State);

• Detached: not tracked by the context; SaveChanges does nothing
• Unchanged: loaded but not modified; SaveChanges does nothing
• Added: new entity, not yet in the database; produces an INSERT
• Modified: loaded and changed; produces an UPDATE
• Deleted: marked for deletion; produces a DELETE

Tracking in Action

// 1. Entity is loaded → state: Unchanged
var order = await context.Orders.FirstAsync(o => o.Id == orderId);

// 2. Modify a property → state: Modified
order.Status = OrderStatus.Confirmed;

// 3. SaveChanges → generates UPDATE for Status column only
await context.SaveChangesAsync();

EF Core knows exactly which columns changed. If you loaded an Order with 15 columns but changed only Status, the generated SQL is:

UPDATE "Orders" SET "Status" = @p0 WHERE "Id" = @p1;

Adding Entities

// Option 1: DbSet.Add
context.Orders.Add(new Order { Id = Guid.NewGuid(), Status = OrderStatus.Draft });

// Option 2: context.Add
context.Add(newOrder);

// Option 3: Add parent, children are tracked automatically
var order = new Order();
order.AddLineItem(productId, quantity, price);

context.Orders.Add(order); // Order AND its LineItems marked as Added
await context.SaveChangesAsync(); // Inserts Order AND LineItems

No-Tracking Queries

If you only need to read data (no updates), skip tracking:

// Single query
var orders = await context.Orders
    .AsNoTracking()
    .Where(o => o.Status == OrderStatus.Confirmed)
    .ToListAsync();

// All queries in a context
context.ChangeTracker.QueryTrackingBehavior =
    QueryTrackingBehavior.NoTracking;

// Or configure at registration
services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString)
           .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));

No-tracking queries are faster because EF Core skips snapshot creation and identity resolution. Skipping tracking on read-only queries is one of the easiest wins among EF Core query performance mistakes.

One variant worth knowing: AsNoTrackingWithIdentityResolution(). It skips snapshots but still deduplicates entities by primary key, so a query with joins doesn't materialize the same Customer five times.

Inspecting the Change Tracker

See what the change tracker knows:

// All tracked entities
foreach (var entry in context.ChangeTracker.Entries())
{
    Console.WriteLine($"{entry.Entity.GetType().Name}: {entry.State}");
}

// Only modified entities
var modified = context.ChangeTracker.Entries()
    .Where(e => e.State == EntityState.Modified);

// Modified properties on a specific entity
var orderEntry = context.Entry(order);
foreach (var prop in orderEntry.Properties)
{
    if (prop.IsModified)
    {
        Console.WriteLine(
            $"{prop.Metadata.Name}: " +
            $"{prop.OriginalValue} → {prop.CurrentValue}");
    }
}

Intercepting Changes (Audit Trails)

Use the change tracker to automatically set audit fields. For a full audit trail with old and new values, see audit logging with EF Core interceptors.

public override async Task<int> SaveChangesAsync(
    CancellationToken ct = default)
{
    var now = DateTime.UtcNow;

    foreach (var entry in ChangeTracker.Entries<IAuditable>())
    {
        switch (entry.State)
        {
            case EntityState.Added:
                entry.Entity.CreatedAt = now;
                entry.Entity.UpdatedAt = now;
                break;

            case EntityState.Modified:
                entry.Entity.UpdatedAt = now;
                break;
        }
    }

    return await base.SaveChangesAsync(ct);
}

Soft delete is another common pattern:

var now = DateTime.UtcNow;

foreach (var entry in ChangeTracker.Entries<ISoftDeletable>())
{
    if (entry.State == EntityState.Deleted)
    {
        entry.State = EntityState.Modified;
        entry.Entity.IsDeleted = true;
        entry.Entity.DeletedAt = now;
    }
}

Identity Resolution

The change tracker ensures only one instance of an entity exists per primary key:

var order1 = await context.Orders.FindAsync(orderId);
var order2 = await context.Orders.FindAsync(orderId);

// Same object reference
Console.WriteLine(ReferenceEquals(order1, order2)); // True

The second call returns the tracked instance without hitting the database. This is called identity resolution and prevents conflicting changes.

DetectChanges

EF Core calls DetectChanges automatically before SaveChangesAsync. It compares current property values to the stored snapshots:

// Automatic detection (default)
order.Status = OrderStatus.Shipped;
await context.SaveChangesAsync(); // DetectChanges called internally

// Manual detection
context.ChangeTracker.DetectChanges();

For performance-critical scenarios with many tracked entities, you can disable automatic detection:

context.ChangeTracker.AutoDetectChangesEnabled = false;

// Manually detect when needed
context.ChangeTracker.DetectChanges();
await context.SaveChangesAsync();

Performance Implications

The change tracker has a cost. The more entities you track, the more snapshots EF Core maintains in memory.

Batch Operations

For bulk updates, skip the change tracker:

// ❌ Slow - loads all entities into memory, tracks each one
var orders = await context.Orders
    .Where(o => o.Status == OrderStatus.Draft &&
                o.CreatedAt < cutoffDate)
    .ToListAsync();

foreach (var order in orders)
    order.Status = OrderStatus.Expired;

await context.SaveChangesAsync(); // N UPDATE statements

// ✅ Fast - single SQL statement, no tracking
await context.Orders
    .Where(o => o.Status == OrderStatus.Draft &&
                o.CreatedAt < cutoffDate)
    .ExecuteUpdateAsync(s =>
        s.SetProperty(o => o.Status, OrderStatus.Expired));

ExecuteUpdateAsync (EF Core 7+) generates a single SQL statement. No entities are loaded or tracked. There are important caveats around tracked entities going stale - I cover them in EF Core bulk updates.

Clear the Tracker

For long-running operations:

context.ChangeTracker.Clear();

This detaches all entities. Useful in background jobs that process many records.

Common Pitfalls

Detached entities: Entities from a different DbContext instance aren't tracked:

// Entity loaded in one scope
var order = await GetOrderFromAnotherMethod();

// Trying to update in a new scope
context.Orders.Update(order); // Marks ALL properties as modified

Use Attach + set specific properties instead:

context.Orders.Attach(order);
context.Entry(order).Property(o => o.Status).IsModified = true;

Update vs Attach: Update marks everything as modified. Attach marks nothing as modified:

context.Update(order);  // State: Modified (all columns in UPDATE)
context.Attach(order);  // State: Unchanged (you set modifications manually)

Sharing a DbContext across threads: the change tracker is not thread-safe. Running parallel queries against the same context corrupts its internal state. See DbContext is not thread-safe for the right way to parallelize EF Core queries.

Summary

Tracking is valuable when a unit of work will modify an entity and call SaveChanges. Read models should usually use projections or AsNoTracking, while set-based updates belong in ExecuteUpdateAsync or ExecuteDeleteAsync. Keeping the tracked graph small makes both behavior and memory use easier to reason about.

An endpoint can look fast with five rows and collapse when it returns five hundred. Detecting the pattern requires looking at the query count, then choosing an explicit loading or projection strategy.

What Is the N+1 Problem?

You load 100 orders, then for each order you load its line items. That's 1 query for orders + 100 queries for line items = 101 database round trips.

// ❌ N+1 problem - 101 queries for 100 orders
var orders = await _db.Orders.ToListAsync();

foreach (var order in orders)
{
    // Each iteration triggers a lazy-load query
    var total = order.LineItems.Sum(li => li.Price * li.Quantity);
    Console.WriteLine($"Order {order.Id}: {total}");
}

With lazy loading enabled, accessing order.LineItems triggers a separate query for each order. The SQL output looks like:

-- Query 1: Get all orders
SELECT * FROM "Orders";

-- Query 2..101: Get line items for each order
SELECT * FROM "LineItems" WHERE "OrderId" = @p0;
SELECT * FROM "LineItems" WHERE "OrderId" = @p1;
SELECT * FROM "LineItems" WHERE "OrderId" = @p2;
-- ... 97 more

This is extremely slow, especially with network latency to the database.

Fix 1: Eager Loading With Include

Load related data in a single query:

// ✅ 1 query - eager loading
var orders = await _db.Orders
    .Include(o => o.LineItems)
    .ToListAsync();

foreach (var order in orders)
{
    var total = order.LineItems.Sum(li => li.Price * li.Quantity);
}

SQL:

SELECT o.*, li.*
FROM "Orders" o
LEFT JOIN "LineItems" li ON o."Id" = li."OrderId";

One query. One round trip. All data loaded.

Nested Includes

var orders = await _db.Orders
    .Include(o => o.LineItems)
        .ThenInclude(li => li.Product)
    .Include(o => o.Customer)
    .ToListAsync();

Filtered Includes (EF Core 5+)

var orders = await _db.Orders
    .Include(o => o.LineItems.Where(li => li.Quantity > 0))
    .ToListAsync();

Fix 2: Split Queries

A single query with multiple Includes can produce a cartesian explosion. Use split queries:

var orders = await _db.Orders
    .Include(o => o.LineItems)
    .Include(o => o.Payments)
    .AsSplitQuery()
    .ToListAsync();

This generates a small, fixed number of queries - one base query plus one per included collection - instead of one giant join:

-- Query 1
SELECT * FROM "Orders";

-- Query 2 (joined against the same Orders filter)
SELECT li.* FROM "LineItems" li
INNER JOIN "Orders" o ON li."OrderId" = o."Id";

-- Query 3
SELECT p.* FROM "Payments" p
INNER JOIN "Orders" o ON p."OrderId" = o."Id";

That's 3 round trips regardless of how many orders you load - a fixed cost, unlike N+1. Two caveats: more round trips add latency, and the queries can observe different data if rows change between them (wrap in a transaction if that matters). The split-versus-single-query tradeoff is covered in EF Core query splitting.

Configure globally:

options.UseNpgsql(connectionString, o =>
{
    o.UseQuerySplittingBehavior(
        QuerySplittingBehavior.SplitQuery);
});

Fix 3: Projection

Only load what you need:

// ✅ Most efficient - single query, minimal data
var orderSummaries = await _db.Orders
    .Select(o => new OrderSummaryDto
    {
        OrderId = o.Id,
        CustomerName = o.Customer.Name,
        ItemCount = o.LineItems.Count,
        Total = o.LineItems.Sum(li => li.Price * li.Quantity)
    })
    .ToListAsync();

No N+1 problem because EF Core computes everything in SQL:

SELECT
    o."Id" AS "OrderId",
    c."Name" AS "CustomerName",
    (SELECT COUNT(*) FROM "LineItems" li WHERE li."OrderId" = o."Id") AS "ItemCount",
    (SELECT SUM(li."Price" * li."Quantity") FROM "LineItems" li WHERE li."OrderId" = o."Id") AS "Total"
FROM "Orders" o
JOIN "Customers" c ON o."CustomerId" = c."Id";

Projection is the best approach when you don't need the full entity graph.

Fix 4: Explicit Loading

Load related data on demand for specific entities:

var order = await _db.Orders.FindAsync(orderId);

// Explicitly load the collection
await _db.Entry(order)
    .Collection(o => o.LineItems)
    .LoadAsync();

// Now access without triggering lazy loading
var total = order.LineItems.Sum(li => li.Price * li.Quantity);

Better than lazy loading because you control when the query happens.

Detecting N+1 Problems

Option 1: SQL Logging

options.UseNpgsql(connectionString)
    .LogTo(Console.WriteLine, LogLevel.Information)
    .EnableSensitiveDataLogging();

Watch for repeated similar queries in the console output. More options for this are in how to log SQL queries in EF Core.

Option 2: EF Core Interceptor

public class QueryCountInterceptor : DbCommandInterceptor
{
    private int _queryCount;

    public override ValueTask<InterceptionResult<DbDataReader>> ReaderExecutingAsync(
        DbCommand command,
        CommandEventData eventData,
        InterceptionResult<DbDataReader> result,
        CancellationToken cancellationToken = default)
    {
        _queryCount++;

        if (_queryCount > 10)
        {
            Console.WriteLine(
                $"⚠️ {_queryCount} queries executed! Possible N+1.");
        }

        return base.ReaderExecutingAsync(
            command, eventData, result, cancellationToken);
    }
}

Register it as scoped so the counter resets per request. Async queries (ToListAsync and friends) only hit the async interception methods, so override ReaderExecuting as well if any code path uses synchronous execution.

Option 3: MiniProfiler

MiniProfiler highlights duplicate queries automatically:

builder.Services.AddMiniProfiler(options =>
{
    options.RouteBasePath = "/profiler";
}).AddEntityFramework();

Disable Lazy Loading

The simplest way to prevent N+1 - don't enable lazy loading in the first place:

// ❌ Enables lazy loading - invites N+1
options.UseLazyLoadingProxies();

// ✅ Default - no lazy loading
// Accessing unloaded navigation returns null or empty collection
options.UseNpgsql(connectionString);

Without lazy loading, unloaded navigations simply stay unpopulated: reference navigations are null, and collection navigations hold whatever you initialized them to (typically an empty list). This forces you to explicitly load what you need - and makes missing data obvious in testing instead of silently slow in production.

The N+1 problem is one of several EF Core query performance mistakes worth auditing your codebase for.

Quick Reference

• Include: when you need full entities with their children; 1 query (or a few, if split)
• AsSplitQuery: when multiple includes cause a cartesian explosion; one base query plus one per included collection
• Select projection: for read-only scenarios needing specific fields; 1 query, minimal data
• Explicit loading: for loading children of a single entity on demand; 1 extra query per LoadAsync
• Dapper or raw SQL: when you need maximum control; exactly the SQL you write

Summary

The N+1 problem can turn one query into hundreds of network round trips. Prefer a projection for read models, Include for entity graphs, and split queries when one joined result would duplicate too much data. Keep lazy loading disabled by default and verify query counts on representative data with logging, an interceptor, or a profiler.

Eager loading is the best default for most scenarios. Use explicit loading for conditional paths, and avoid lazy loading in production.

The Related Data Problem

When you query an Order, should EF Core also load the OrderLineItems? What about the Customer? Loading everything upfront is wasteful. Loading nothing means extra round trips later.

EF Core provides three strategies: eager loading, explicit loading, and lazy loading. Understanding when to use each one is critical for performance.

Eager Loading With Include

Eager loading fetches related data in the same query using Include and ThenInclude:

var order = await context.Orders
    .Include(o => o.LineItems)
    .Include(o => o.Customer)
    .FirstOrDefaultAsync(o => o.Id == orderId);

EF Core generates a single query with JOINs:

SELECT o.*, li.*, c.*
FROM "Orders" o
LEFT JOIN "OrderLineItems" li ON li."OrderId" = o."Id"
LEFT JOIN "Customers" c ON c."Id" = o."CustomerId"
WHERE o."Id" = @p0;

For nested relationships, use ThenInclude:

var order = await context.Orders
    .Include(o => o.LineItems)
        .ThenInclude(li => li.Product)
    .FirstOrDefaultAsync(o => o.Id == orderId);

Filtered Includes

Since EF Core 5, you can filter what gets included:

var order = await context.Orders
    .Include(o => o.LineItems
        .Where(li => li.Quantity > 0)
        .OrderBy(li => li.Price))
    .FirstOrDefaultAsync(o => o.Id == orderId);

This is useful when you don't need all related entities - only a subset.

When to Use Eager Loading

Eager loading is the best default for most scenarios. You know exactly which relationships you need upfront, and EF Core fetches them in a single round trip. The downside is that large Include chains can produce massive SQL queries with many JOINs.

When you include multiple sibling collections, the joined result set multiplies (a cartesian explosion). Use AsSplitQuery() in those cases, and measure the round-trip versus duplication tradeoff described in EF Core query splitting.

Explicit Loading

Explicit loading lets you load related data on demand after the parent entity is already in memory:

var order = await context.Orders
    .FirstOrDefaultAsync(o => o.Id == orderId);

// Load line items explicitly
await context.Entry(order)
    .Collection(o => o.LineItems)
    .LoadAsync();

// Load a single reference
await context.Entry(order)
    .Reference(o => o.Customer)
    .LoadAsync();

Each LoadAsync call issues a separate SELECT query. This gives you fine-grained control over when data is fetched.

Querying Before Loading

You can also apply filters or projections before loading:

var expensiveItems = await context.Entry(order)
    .Collection(o => o.LineItems)
    .Query()
    .Where(li => li.Price > 100)
    .ToListAsync();

The Query() method returns an IQueryable that you can chain with any LINQ operator. This avoids loading the entire collection when you only need a subset.

When to Use Explicit Loading

Explicit loading works well when:

• You conditionally need related data based on runtime logic
• You want to avoid massive JOIN queries
• You've loaded an entity from the change tracker and need its relationships later

Lazy Loading

Lazy loading automatically fetches related data the first time you access a navigation property. EF Core intercepts the property access and issues a query behind the scenes.

Setting Up Lazy Loading

Install the Microsoft.EntityFrameworkCore.Proxies package and enable it:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString)
           .UseLazyLoadingProxies());

Mark navigation properties as virtual so EF Core can create proxy classes:

public class Order
{
    public Guid Id { get; set; }
    public OrderStatus Status { get; set; }

    public Guid CustomerId { get; set; }
    public virtual Customer Customer { get; set; }

    public virtual ICollection<OrderLineItem> LineItems { get; set; }
}

Now accessing order.LineItems triggers a query automatically:

var order = await context.Orders
    .FirstOrDefaultAsync(o => o.Id == orderId);

// This triggers a SELECT query for line items
foreach (var item in order.LineItems)
{
    // This triggers ANOTHER query for each product
    Console.WriteLine(item.Product.Name);
}

The N+1 Problem

That last example has a serious performance problem. If the order has 50 line items, accessing item.Product in the loop fires 50 separate queries - one for each product. Combined with the initial order query and the line items query, that's 52 queries total.

This is the N+1 problem, and it's the biggest risk of lazy loading. Everything looks correct, but the app is hammering the database.

Lazy Loading Without Proxies

If you want lazy loading for a specific entity without proxying your whole model, EF Core supports injecting ILazyLoader:

public class Order
{
    private readonly ILazyLoader _lazyLoader;
    private List<OrderLineItem> _lineItems;

    public Order()
    {
    }

    private Order(ILazyLoader lazyLoader)
    {
        _lazyLoader = lazyLoader;
    }

    public List<OrderLineItem> LineItems
    {
        get => _lazyLoader.Load(this, ref _lineItems);
        set => _lineItems = value;
    }
}

EF Core injects ILazyLoader through the private constructor when it materializes the entity. The Load extension method (from Microsoft.EntityFrameworkCore.Infrastructure) queries the collection on first access and is a no-op when the loader is null, so new Order() still works in tests. It is more explicit than proxies, but it couples entities to an EF Core interface and rarely justifies that tradeoff.

Detecting N+1 Queries

You can log SQL queries to catch this in development:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString)
           .LogTo(Console.WriteLine, LogLevel.Information)
           .EnableSensitiveDataLogging());

If you see a pattern of many similar SELECT statements inside a loop, you've found an N+1 problem.

Comparing the Three Strategies

• Eager loading: one query with JOINs (or split queries), you decide upfront what to load, no N+1 risk. Best for relationships you always need.
• Explicit loading: one query per LoadAsync call, full on-demand control, low N+1 risk. Best for conditional loading.
• Lazy loading: one query per navigation property access, fully automatic, high N+1 risk. Acceptable for prototyping, dangerous in production.

My Recommendations

A practical default is:

Use eager loading as the default. When you write a query, you almost always know what related data you need. Use Include to fetch it upfront.

Use explicit loading for conditional paths. If you only need line items when the order status is Confirmed, use explicit loading to avoid unnecessary data.

Avoid lazy loading in production. Lazy loading hides database queries behind property access. It makes performance problems invisible until they hit production. If you must use it, treat it as a shortcut for prototyping - not a production strategy.

// ✅ Eager - clear intent, single round trip
var order = await context.Orders
    .Include(o => o.LineItems)
        .ThenInclude(li => li.Product)
    .Include(o => o.Customer)
    .FirstOrDefaultAsync(o => o.Id == orderId);

// ✅ Explicit - conditional loading
var order = await context.Orders
    .FirstOrDefaultAsync(o => o.Id == orderId);

if (order.Status == OrderStatus.Confirmed)
{
    await context.Entry(order)
        .Collection(o => o.LineItems)
        .LoadAsync();
}

// ❌ Lazy - hidden queries, N+1 risk
foreach (var item in order.LineItems) // hidden query
{
    Console.WriteLine(item.Product.Name); // hidden query per item
}

Summary

Use a projection or eager loading when the query already knows which related data it needs. Use explicit loading when the decision depends on state discovered after the entity is loaded. Lazy loading hides network calls behind property access, so enable it only with query-count visibility and a deliberate reason.

Why Are My EF Core Queries Slow?

EF Core generates SQL from your LINQ queries. The SQL it generates is only as good as the LINQ you write.

These are the query-shape mistakes that most often turn straightforward LINQ into expensive database work.

Mistake 1: N+1 Queries

The most notorious performance problem. You load a list of orders, then access each order's customer in a loop:

// ✗ N+1 problem - 1 query for orders + N queries for customers
var orders = await dbContext.Orders.ToListAsync();

foreach (var order in orders)
{
    Console.WriteLine(order.Customer.Name); // Lazy load triggers a query
}

If you have 100 orders, this executes 101 queries. I dig into detection and every fix in detail in the N+1 query problem in EF Core.

Fix: Use eager loading or projections:

// ✓ Eager loading - 1 query with JOIN
var orders = await dbContext.Orders
    .Include(o => o.Customer)
    .ToListAsync();

// ✓ Even better - projection, only fetches needed columns
var orderSummaries = await dbContext.Orders
    .Select(o => new
    {
        o.Id,
        CustomerName = o.Customer.Name,
        o.TotalAmount
    })
    .ToListAsync();

Projections are usually the better fit for read models because they select only the columns the result needs.

Mistake 2: Loading Entire Tables

// ✗ Loads ALL orders into memory, then filters
var expensiveOrders = dbContext.Orders
    .ToList() // Everything loaded here
    .Where(o => o.TotalAmount > 1000);

The .ToList() before .Where() materializes the entire table. The filtering happens in C#, not SQL.

Fix: Filter before materializing:

// ✓ SQL WHERE clause - only matching rows returned
var expensiveOrders = await dbContext.Orders
    .Where(o => o.TotalAmount > 1000)
    .ToListAsync();

Rule of thumb: Call .ToListAsync() or .FirstOrDefaultAsync() as the last operation.

Mistake 3: Loading Entities for Read-Only Operations

// ✗ Loads full Order entity with change tracking
var order = await dbContext.Orders
    .Include(o => o.LineItems)
    .Include(o => o.Customer)
    .FirstOrDefaultAsync(o => o.Id == orderId);

return new OrderResponse(
    order.Id,
    order.Customer.Name,
    order.TotalAmount,
    order.Status.ToString());

You loaded a full entity graph with change tracking, just to map it to a DTO. Wasteful.

Fix: Project directly into the DTO:

// ✓ No entity loading, no change tracking, minimal SQL
var response = await dbContext.Orders
    .Where(o => o.Id == orderId)
    .Select(o => new OrderResponse(
        o.Id,
        o.Customer.Name,
        o.TotalAmount,
        o.Status.ToString()))
    .FirstOrDefaultAsync();

Or use AsNoTracking() if you must load entities:

// ✓ At least skip change tracking
var order = await dbContext.Orders
    .AsNoTracking()
    .FirstOrDefaultAsync(o => o.Id == orderId);

Mistake 4: Missing Pagination

// ✗ Returns every order in the database
var orders = await dbContext.Orders.ToListAsync();

Fix: Always paginate collection queries:

// ✓ Fetches only one page
var orders = await dbContext.Orders
    .OrderBy(o => o.CreatedAt)
    .Skip((page - 1) * pageSize)
    .Take(pageSize)
    .Select(o => new OrderSummary(o.Id, o.Status, o.TotalAmount))
    .ToListAsync();

For large or frequently-scrolled datasets, cursor-based pagination outperforms offset pagination - see pagination in ASP.NET Core for the tradeoffs.

Mistake 5: Missing Indexes

EF Core creates indexes for primary keys and foreign keys. But your custom queries often need additional indexes.

If your WHERE clause filters on Status and CreatedAt, you need a composite index:

builder.HasIndex(o => new { o.Status, o.CreatedAt })
    .HasDatabaseName("IX_Orders_Status_CreatedAt");

Check your query plans. If you see a sequential scan on a table with millions of rows, you're missing an index.

Mistake 6: Using String Interpolation in Queries

// ✗ SQL injection risk AND prevents query plan caching
var orders = await dbContext.Orders
    .FromSqlRaw($"""SELECT * FROM "Orders" WHERE "Status" = '{status}'""")
    .ToListAsync();

Fix: Use parameterized queries:

// ✓ Parameterized - safe and cacheable
var orders = await dbContext.Orders
    .FromSqlInterpolated($"""SELECT * FROM "Orders" WHERE "Status" = {status}""")
    .ToListAsync();

FromSqlInterpolated automatically parameterizes the interpolated values. FromSqlRaw with string interpolation is a SQL injection vulnerability. In EF Core 7+, FromSql does the same thing as FromSqlInterpolated with a shorter name.

Mistake 7: Cartesian Explosion

Loading multiple collections with Include creates a cartesian product:

// ✗ Cartesian explosion - rows multiply
var order = await dbContext.Orders
    .Include(o => o.LineItems)    // 10 items
    .Include(o => o.Payments)     // 3 payments
    .FirstOrDefaultAsync(o => o.Id == orderId);
// Returns 30 rows (10 x 3) instead of ~13

Fix: Use split queries or separate loads:

// ✓ Split query - separate SQL per Include
var order = await dbContext.Orders
    .Include(o => o.LineItems)
    .Include(o => o.Payments)
    .AsSplitQuery()
    .FirstOrDefaultAsync(o => o.Id == orderId);

EF Core 5+ also has a global setting:

optionsBuilder.UseNpgsql(connectionString, o =>
    o.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery));

Split queries aren't free: they trade one round trip for several, and the queries can observe different data unless wrapped in a transaction. The round-trip and duplication tradeoffs are covered in EF Core query splitting.

Mistake 8: Not Using Compiled Queries for Hot Paths

For queries that execute thousands of times per second:

private static readonly Func<AppDbContext, Guid, Task<Order?>> GetOrderByIdQuery =
    EF.CompileAsyncQuery(
        (AppDbContext db, Guid id) =>
            db.Orders.FirstOrDefault(o => o.Id == id));

// Usage
var order = await GetOrderByIdQuery(dbContext, orderId);

Compiled queries skip repeated LINQ compilation work after the delegate is created. That can matter on hot endpoints with cheap database work, but it should be measured as described in EF Core compiled queries.

Mistake 9: Querying Inside Loops

// ✗ One query per customer
foreach (var customerId in customerIds)
{
    var orders = await dbContext.Orders
        .Where(o => o.CustomerId == customerId)
        .ToListAsync();

    // Process orders
}

Fix: Batch the query:

// ✓ Single query for all customers, grouped in memory
var orders = await dbContext.Orders
    .Where(o => customerIds.Contains(o.CustomerId))
    .ToListAsync();

var ordersByCustomer = orders.ToLookup(o => o.CustomerId);

One round trip instead of N, and the in-memory ToLookup gives you the same per-customer grouping.

Quick Reference

• N+1 queries: use Include() or, better, a Select() projection
• Loading full tables: filter with Where() before ToList()
• Change tracking overhead: use AsNoTracking() or projections
• No pagination: add Skip() + Take(), or cursor pagination
• Missing indexes: add indexes for your WHERE/ORDER BY columns
• SQL injection: use FromSqlInterpolated, never interpolate into FromSqlRaw
• Cartesian explosion: use AsSplitQuery()
• Hot path overhead: use EF.CompileAsyncQuery()
• Queries in loops: batch with Contains()

Summary

Project only the columns the read model needs, support selective predicates with indexes, and paginate every potentially large collection. Watch the generated SQL and query count so N+1 loading and cartesian products cannot hide behind concise LINQ. Optimize from a measured database plan before replacing EF Core or adding a lower-level data-access path.

Layered architecture is the default choice in .NET, and defaults rarely get questioned. But an architecture you picked by inertia is still an architecture decision, just one made without looking at the alternatives.

The Problem With Layers

In a layered architecture, a simple "Get Order by ID" feature touches:

1. OrdersController (Presentation)
2. IOrderService + OrderService (Application)
3. IOrderRepository + OrderRepository (Infrastructure)
4. OrderDto, OrderResponse (Mapping)

Four files across four folders for a database query that returns one object. Adding a new feature means touching every layer. Modifying a feature means jumping between folders.

What Changes Together Should Live Together

Vertical Slice Architecture organizes code by feature instead of layer, and it's easier to adopt than most people think:

// Layered: related code is scattered
Controllers/OrdersController.cs    ← GetOrder, CreateOrder, DeleteOrder
Services/OrderService.cs           ← GetOrder, CreateOrder, DeleteOrder
Repositories/OrderRepository.cs    ← GetOrder, CreateOrder, DeleteOrder

// VSA: related code is co-located
Features/Orders/GetOrder.cs        ← everything for GetOrder
Features/Orders/CreateOrder.cs     ← everything for CreateOrder
Features/Orders/DeleteOrder.cs     ← everything for DeleteOrder

When you work on "Get Order," you open one file. When you review a pull request, the diff shows one file per feature.

When to Choose VSA

Your Features Are Independent

If most features don't share logic, VSA reduces unnecessary abstractions:

// This feature needs no repository, no service layer
public static class GetOrder
{
    public sealed record Query(Guid Id);

    public sealed record OrderResponse(
        Guid Id, string Status, decimal TotalAmount, DateTime CreatedAt);

    public sealed class Handler(ApplicationDbContext db)
    {
        public async Task<OrderResponse?> Handle(
            Query query, CancellationToken ct)
        {
            return await db.Orders
                .Where(o => o.Id == query.Id)
                .Select(o => new OrderResponse(
                    o.Id, o.Status, o.TotalAmount, o.CreatedAt))
                .FirstOrDefaultAsync(ct);
        }
    }
}

No interface, no repository, no service. Just a query that returns data.

Your Team Is Growing

With layers, two developers working on separate features often edit the same files - the same controller, the same service. Merge conflicts happen frequently.

With VSA, each developer works in separate files. Feature A doesn't touch Feature B's code.

You Want Fast Iteration

VSA has less ceremony. Adding a new feature:

1. Create one file
2. Define the request, handler, and endpoint
3. Done

No interface to define, no repository to implement, and assembly scanning handles the registration.

Your Application Is CRUD-Heavy

Many business applications are variations of create-read-update-delete. VSA handles this cleanly:

Features/
  Products/
    CreateProduct.cs      ← 60 lines
    GetProduct.cs         ← 40 lines
    GetProducts.cs        ← 50 lines
    UpdateProduct.cs      ← 70 lines
    DeleteProduct.cs      ← 30 lines

Each file is small and self-contained. No layered abstractions adding complexity without value.

You're Using CQRS

CQRS and VSA are a natural pair. Commands and queries are already separate operations - putting each in its own file is the logical next step:

Features/
  Orders/
    Commands/
      PlaceOrder.cs
      CancelOrder.cs
    Queries/
      GetOrder.cs
      GetOrders.cs

When to Choose Layers

You Have Complex Shared Business Logic

If 10 features all need the same pricing calculation, a PricingService in a service layer makes sense. Duplicating that logic across 10 slices is worse.

You Need Strict Architectural Boundaries

Layers enforce compile-time boundaries. The presentation layer physically cannot reference the database. VSA in a single project doesn't prevent a handler from doing whatever it wants.

Your Team Is Familiar With Layers

Architecture decisions are team decisions. If your team knows layered architecture well and productivity is good, switching to VSA for the sake of switching creates churn without value.

You Have a Rich Domain Model

Domain-Driven Design with a rich domain model benefits from a dedicated domain layer. The domain layer contains complex business rules that multiple features share. Clean Architecture is a better fit here.

The Middle Ground

You don't have to be all-in on either approach. Many successful projects combine both:

src/
  MyApp.Api/
    Features/           ← Vertical slices for individual operations
      Orders/
        PlaceOrder.cs
        GetOrder.cs
    Domain/             ← Shared domain entities (from Clean Architecture)
      Order.cs
      Customer.cs
    Shared/             ← Cross-cutting concerns
      Behaviors/
        ValidationBehavior.cs

Use slices for application logic. Use a domain layer for shared business rules. Use pipeline behaviors for cross-cutting concerns.

Migrating From Layers, Incrementally

Choosing VSA doesn't mean rewriting your layered application. The migration path I recommend:

1. New features go in a Features folder as self-contained slices. Don't touch the existing layers yet.
2. When you modify an existing feature, consider moving it into a slice as part of the change. The controller action, service method, and repository method collapse into one handler.
3. Leave stable code alone. A feature nobody has touched in a year gains nothing from being restructured.
4. Delete layers as they empty out. When OrderService has one method left, inline it and remove the class.

After a few months you have a codebase that's mostly slices with a small legacy core, and you got there without a big-bang rewrite or a feature freeze.

Decision Matrix

Signals that point toward Vertical Slice Architecture:

• Features are largely independent of each other
• The application is CRUD-heavy
• You need fast iteration with minimal ceremony
• The team is growing and works on many features in parallel
• You're already using CQRS

Signals that point toward layers:

• Heavy shared business logic across features
• A rich domain model with DDD
• You need strict compile-time boundaries
• The team is experienced and productive with layers

If your signals land on both sides, that's normal. It usually means the hybrid approach (slices plus a shared domain layer) is your answer.

Summary

Choose Vertical Slice Architecture when:

1. Features are independent and rarely share logic
2. Your team needs parallel development without merge conflicts
3. You value simplicity - one file per feature, no unnecessary abstractions
4. You're already using CQRS (with or without MediatR)
5. The application is CRUD-heavy without complex domain logic

Choose layers when shared business logic, strict boundaries, or DDD richness justifies the overhead.

The best architecture is the one your team can maintain and evolve. Start with what fits your problem, not what's trending.

Thanks for reading, and stay awesome!

Two Different Philosophies

Clean Architecture organizes code by technical layer - Domain, Application, Infrastructure, Presentation. Each layer has clear responsibilities, and dependencies point inward.

Vertical Slice Architecture organizes code by feature - each feature is a self-contained slice that cuts through all layers from UI to database. You don't share code between slices unless it's a genuine cross-cutting concern.

Both are valid. But they optimize for different things.

Clean Architecture in Brief

Clean Architecture separates your solution into concentric layers:

Presentation → Application → Domain ← Infrastructure

The dependency rule: inner layers define abstractions, outer layers implement them.

A typical project structure:

MyApp.Domain/         ← Entities, Value Objects, Interfaces
MyApp.Application/    ← Use Cases, DTOs, Validators
MyApp.Infrastructure/ ← EF Core, External APIs
MyApp.Api/            ← Controllers, Endpoints

Adding a new feature means touching multiple projects: define the entity in Domain, add a command/handler in Application, configure persistence in Infrastructure, add an endpoint in Presentation.

Vertical Slice Architecture in Brief

Vertical Slice Architecture groups everything for a feature together:

Features/
  PlaceOrder/
    PlaceOrderEndpoint.cs
    PlaceOrderCommand.cs
    PlaceOrderHandler.cs
    PlaceOrderValidator.cs
  GetOrderById/
    GetOrderByIdEndpoint.cs
    GetOrderByIdQuery.cs
    GetOrderByIdHandler.cs
    OrderResponse.cs

Adding a new feature means creating a new folder with all the code for that feature. You don't modify existing features.

Key Differences

Coupling Direction

Clean Architecture couples by layer. All repositories live together. All entities live together. Changing how repositories work could affect many features.

Vertical Slices couple by feature. Each feature is independent. Changing the PlaceOrder feature doesn't affect GetOrderById.

Code Reuse

Clean Architecture encourages code reuse across features. A shared OrderRepository serves every use case that needs orders.

Vertical Slices minimize shared code. Each feature can query the database differently. PlaceOrder might use a repository; GetOrderById might use raw Dapper.

Consistency

Clean Architecture enforces consistency. Every feature follows the same patterns - same handler structure, same validation approach, same repository layer.

Vertical Slices allow variation. Simple CRUD features can be simple. Complex features can use rich domain models. Each slice uses what it needs.

Indirection

Clean Architecture adds layers of indirection. To trace a request from endpoint to database, you pass through multiple abstractions: endpoint → handler → repository → DbContext.

Vertical Slices minimize indirection. A simple query handler might go straight to the database with no intermediate abstractions.

Side-by-Side Comparison

Here's how the two approaches stack up, dimension by dimension:

When to Choose Clean Architecture

Choose Clean Architecture when:

1. Your domain is complex. If you have rich business rules, invariants, and domain events, Clean Architecture gives you the structure to manage that complexity.

2. Multiple features share domain logic. If your Order entity is used by PlaceOrder, CancelOrder, RefundOrder, and ShipOrder - sharing it through a Domain layer makes sense.

3. You want strict architectural boundaries. Clean Architecture's layers can be enforced with architecture tests, giving you confidence that infrastructure doesn't leak into your domain.

4. Your team is large and values uniformity. One enforced pattern for every use case keeps dozens of developers producing code that looks the same, which pays off in reviews and onboarding.

5. The project is long-lived. The upfront investment in structure pays off over years as the codebase grows.

When to Choose Vertical Slice Architecture

Choose Vertical Slices when:

1. Features have different complexity. Some endpoints are simple CRUD, others have complex workflows. Vertical slices let each feature use the appropriate level of abstraction.

2. You want fast feature delivery. New features are self-contained. You don't need to understand the entire repository layer to add a new query.

3. Your team is small. Less infrastructure to maintain. Fewer abstractions to navigate.

4. You're building a CRUD-heavy API. If most features are thin wrappers around database operations, layers add overhead without value.

5. You want to minimize coupling. Features that don't share code can be modified and tested in isolation, without touching the rest of the system.

Can You Combine Them?

Yes. And many teams do.

A common approach: use Vertical Slices for feature organization inside a Clean Architecture solution structure.

MyApp.Application/
  Features/
    Orders/
      PlaceOrder/
        PlaceOrderCommand.cs
        PlaceOrderCommandHandler.cs
      GetOrderById/
        GetOrderByIdQuery.cs
        GetOrderByIdQueryHandler.cs
    Customers/
      RegisterCustomer/
        RegisterCustomerCommand.cs
        RegisterCustomerCommandHandler.cs

You get:

• Feature-based organization (vertical slices)
• Layer boundaries enforced at the project level (Clean Architecture)
• Shared domain model for complex business rules
• Independent use cases that don't affect each other

This hybrid approach is what I use in my Pragmatic Clean Architecture course. It gives you the best of both worlds.

Common Mistakes

1. Using Clean Architecture for everything. A simple API with five CRUD endpoints doesn't need four projects and a dozen abstractions.

2. Duplicating everything in Vertical Slices. If three features need the same validation logic, extract it. "Minimize code sharing" doesn't mean "never share code."

3. Choosing based on popularity, not fit. Clean Architecture is more popular in .NET. That doesn't make it the right choice for every project.

4. Thinking it's permanent. You can start with Vertical Slices and introduce layer boundaries as complexity grows. Architecture should evolve with your project. If you're unsure where your project falls, I've written about when to choose Vertical Slice Architecture in more detail.

Summary

Clean Architecture and Vertical Slice Architecture solve different problems:

• Clean Architecture manages complexity through layer discipline
• Vertical Slices manage complexity through feature isolation

For complex domains with shared business rules → Clean Architecture. For varied features with different complexity levels → Vertical Slices. For most real projects → a pragmatic combination of both.

Thanks for reading, and stay awesome!

Vertical Slice Architecture sounds simple until you create the solution and have to decide where everything goes. Where do domain entities live? Does the DbContext get its own project? This article answers those questions with a concrete layout, and shows how it evolves as the project grows.

The Problem With Layered Folders

In a traditional layered project, you get folders like this:

Controllers/
  OrdersController.cs
  CustomersController.cs
  ProductsController.cs
Services/
  OrderService.cs
  CustomerService.cs
  ProductService.cs
Repositories/
  OrderRepository.cs
  CustomerRepository.cs
  ProductRepository.cs
Models/
  Order.cs
  Customer.cs
  Product.cs

To understand how "Place Order" works, you jump between 4+ folders. Adding a feature means touching multiple folders. Related code is scattered.

Vertical Slice Architecture fixes this by organizing code around features. This article is about the practical part: the actual folder and solution layout, and how it holds up as the feature count grows.

For what goes inside a slice (the command, handler, and validator structure), see my newsletter issue on structuring vertical slices. Here we stay at the folder level.

The Starting Layout: 5-15 Features

One project, one Features folder, one file per use case:

Features/
  Orders/
    PlaceOrder.cs
    GetOrder.cs
    GetOrders.cs
    CancelOrder.cs
    OrdersModule.cs
  Customers/
    RegisterCustomer.cs
    GetCustomer.cs
    UpdateCustomer.cs
    CustomersModule.cs
  Products/
    CreateProduct.cs
    GetProducts.cs
    SearchProducts.cs
    ProductsModule.cs

Everything for "Place Order" is in one file. Everything for orders is in one folder. The *Module.cs file per folder registers that feature group's endpoints (a Carter module or a plain extension method, your choice).

Two naming rules keep this navigable:

• Files are verbs: PlaceOrder.cs, not OrderService.cs. The folder listing reads like a feature list.
• One use case per file: if a file handles two operations, it's two slices pretending to be one.

Full Project Structure

Here's the complete single-project layout I use:

src/
  MyApp.Api/
    Features/
      Orders/
        PlaceOrder.cs
        GetOrder.cs
        GetOrders.cs
        CancelOrder.cs
        UpdateOrderStatus.cs
        OrdersModule.cs
      Customers/
        RegisterCustomer.cs
        GetCustomer.cs
        GetCustomers.cs
        UpdateCustomer.cs
        CustomersModule.cs
      Products/
        CreateProduct.cs
        GetProducts.cs
        SearchProducts.cs
        ProductsModule.cs
    Domain/
      Order.cs
      Customer.cs
      Product.cs
      Common/
        Entity.cs
        Result.cs
        Error.cs
    Data/
      ApplicationDbContext.cs
      Configurations/
        OrderConfiguration.cs
        CustomerConfiguration.cs
        ProductConfiguration.cs
      Migrations/
    Shared/
      Behaviors/
        ValidationBehavior.cs
        LoggingBehavior.cs
      Middleware/
        ExceptionHandlingMiddleware.cs
    Program.cs
tests/
  MyApp.Api.Tests/
    Features/
      Orders/
        PlaceOrderTests.cs
        GetOrderTests.cs
      Customers/
        RegisterCustomerTests.cs

Note that the test project mirrors the Features tree exactly. Finding the tests for a slice should never require a search.

Key Decisions

One Project or Multiple?

Single project - the default for VSA. Keep it simple:

MyApp.Api/
  Features/
  Domain/
  Data/
  Shared/

Multiple projects - only when you need strict compile-time enforcement:

MyApp.Api/          ← entry point
MyApp.Features/     ← all features
MyApp.Domain/       ← domain entities
MyApp.Data/         ← EF Core, migrations

Start with one project. Split when you have a reason. Folder boundaries are cheap to change; project boundaries are not. If you want boundary enforcement without extra projects, architecture tests on namespaces get you most of the way.

Where Do Domain Entities Live?

In a Domain/ folder within the same project:

Domain/
  Order.cs
  LineItem.cs
  Customer.cs
  Product.cs
  Common/
    Entity.cs
    AggregateRoot.cs
    IDomainEvent.cs

Domain entities are shared across features. An Order entity is used by PlaceOrder, GetOrder, and CancelOrder. Slices own their request and response types; they share the domain model underneath.

Where Does the DbContext Live?

In a Data/ folder:

Data/
  ApplicationDbContext.cs
  Configurations/
    OrderConfiguration.cs
    CustomerConfiguration.cs
  Migrations/

EF Core configurations are separate from features - they're infrastructure, not business logic.

Shared Code (Cross-Cutting Concerns)

Pipeline behaviors, middleware, and shared abstractions in Shared/:

Shared/
  Behaviors/
    ValidationBehavior.cs
    LoggingBehavior.cs
    CachingBehavior.cs
  Middleware/
    ExceptionHandlingMiddleware.cs
    RequestLoggingMiddleware.cs
  Abstractions/
    ICommand.cs
    IQuery.cs
    ICacheable.cs
  Extensions/
    ResultExtensions.cs

Keep this folder small and boring. If Shared starts accumulating business logic, a slice boundary is leaking; see cross-cutting concerns in Vertical Slice Architecture for what belongs here and what doesn't.

When Features Get Complex

A simple feature fits in one file. A complex feature graduates to a folder:

Features/
  Orders/
    PlaceOrder/
      PlaceOrderCommand.cs
      PlaceOrderHandler.cs
      PlaceOrderValidator.cs
      PlaceOrderResponse.cs
    GetOrder/
      GetOrderQuery.cs
      GetOrderHandler.cs
    Shared/
      OrderResponse.cs
    OrdersModule.cs

My threshold: split into a folder when the single file grows past roughly 150-200 lines, or when a slice needs private helper classes that would pollute the file.

A feature-local Shared/ folder (like Orders/Shared/) is fine for DTOs reused by two or three sibling slices, like the OrderResponse that both GetOrder and GetOrders return. It's still inside the feature boundary, which is very different from a global shared folder.

Scaling to 50+ Features

A flat Features folder stops working around a few dozen slices. The fix is one more level: group by domain area.

Features/
  Ordering/
    PlaceOrder.cs
    GetOrder.cs
    CancelOrder.cs
    OrderingModule.cs
  Catalog/
    CreateProduct.cs
    SearchProducts.cs
    CatalogModule.cs
  Identity/
    RegisterUser.cs
    Login.cs
    RefreshToken.cs
    IdentityModule.cs
  Shipping/
    CreateShipment.cs
    TrackShipment.cs
    ShippingModule.cs

These groups aren't arbitrary. They mirror bounded contexts, and each one is a candidate module if you later evolve toward a modular monolith. At that point each domain area gets its own project (or set of projects), and the folder structure you already have becomes the module structure. I've written about exactly where vertical slices fit inside a modular monolith.

The practical signals that you've hit this stage:

• You scroll to find anything in Features/
• Two domain areas keep reaching into each other's entities
• Different teams own different feature groups and step on each other in PRs

Restructuring is mechanical: create the domain-area folders, move files, fix namespaces. Do it in one PR before the pain compounds.

Conventions That Keep the Structure Healthy

A folder structure only stays clean if a few conventions back it up:

• Namespace mirrors folder. MyApp.Api.Features.Ordering.PlaceOrder tells you exactly where the file lives. Most IDEs enforce this automatically.
• Handlers are internal. Nothing outside the slice should call a handler directly. The endpoint (or dispatcher) is the only entry point.
• One route prefix per module. OrdersModule owns /api/orders; no other module maps routes under it.
• No slice-to-slice references. If PlaceOrder needs something from Shipping, that's a domain service or a domain event, not a using statement. A couple of architecture tests will hold this line for you.

Summary

A practical VSA folder structure:

1. Features folder - one file per use case, named as a verb
2. Domain folder - shared entities and value objects
3. Data folder - DbContext, configurations, migrations
4. Shared folder - pipeline behaviors, middleware, abstractions (keep it boring)
5. Single project to start, split only when you need compile-time boundaries
6. Single-file slices first, folders past ~150-200 lines
7. Domain-area grouping at 50+ features, mirroring bounded contexts

The structure should make it obvious what your application does by reading the feature folder names.

Thanks for reading, and stay awesome!

Minimal APIs are great until Program.cs hits 500 lines.

What Is Carter?

Carter is a library that adds convention-based routing to ASP.NET Core Minimal APIs. It lets you define endpoints in self-contained modules instead of one giant Program.cs.

Combined with Vertical Slice Architecture, Carter gives each feature its own endpoint module, handler, and model - all in one place.

Setting Up Carter

Install the package:

dotnet add package Carter

Register it:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCarter();

builder.Services.AddMediatR(config =>
{
    config.RegisterServicesFromAssembly(typeof(Program).Assembly);
    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
});

builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

var app = builder.Build();

app.MapCarter();
app.Run();

MapCarter() automatically discovers all ICarterModule implementations and registers their routes.

ValidationBehavior is the FluentValidation pipeline behavior that runs each slice's validator before the handler and returns failures as a failed Result. I break it down in validation in Vertical Slice Architecture.

A Feature Slice With Carter

Here's a complete feature slice for placing an order:

// Features/Orders/PlaceOrder.cs
public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId,
        List<OrderItemRequest> Items) : IRequest<Result<Guid>>;

    public sealed record OrderItemRequest(Guid ProductId, int Quantity);

    public sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.CustomerId).NotEmpty();
            RuleFor(x => x.Items).NotEmpty();
            RuleForEach(x => x.Items).ChildRules(item =>
            {
                item.RuleFor(x => x.ProductId).NotEmpty();
                item.RuleFor(x => x.Quantity).GreaterThan(0);
            });
        }
    }

    public sealed class Handler : IRequestHandler<Command, Result<Guid>>
    {
        private readonly ApplicationDbContext _db;

        public Handler(ApplicationDbContext db) => _db = db;

        public async Task<Result<Guid>> Handle(
            Command request, CancellationToken ct)
        {
            var customer = await _db.Customers
                .FirstOrDefaultAsync(c => c.Id == request.CustomerId, ct);

            if (customer is null)
            {
                return Result.Failure<Guid>(
                    new Error("Customer.NotFound", "Customer not found."));
            }

            var order = new Order
            {
                Id = Guid.NewGuid(),
                CustomerId = request.CustomerId,
                Items = request.Items.Select(i => new OrderItem
                {
                    ProductId = i.ProductId,
                    Quantity = i.Quantity
                }).ToList(),
                CreatedAt = DateTime.UtcNow
            };

            _db.Orders.Add(order);
            await _db.SaveChangesAsync(ct);

            return order.Id;
        }
    }
}

Now the Carter module:

// Features/Orders/OrdersModule.cs
public class OrdersModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders")
            .WithTags("Orders");

        group.MapPost("", async (
            PlaceOrder.Command command,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(command, ct);

            return result.IsSuccess
                ? Results.Created($"/api/orders/{result.Value}", result.Value)
                : result.ToProblemDetails();
        });

        group.MapGet("{id:guid}", async (
            Guid id,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(new GetOrder.Query(id), ct);

            return result.IsSuccess
                ? Results.Ok(result.Value)
                : result.ToProblemDetails();
        });

        group.MapGet("", async (
            int page,
            int pageSize,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(
                new GetOrders.Query(page, pageSize), ct);

            return Results.Ok(result.Value);
        });
    }
}

ToProblemDetails() is a small extension method that maps a failed Result to Results.Problem or Results.ValidationProblem, so every endpoint returns consistent Problem Details responses.

Project Structure

Features/
  Orders/
    PlaceOrder.cs
    GetOrder.cs
    GetOrders.cs
    CancelOrder.cs
    OrdersModule.cs
  Customers/
    RegisterCustomer.cs
    GetCustomer.cs
    CustomersModule.cs
  Products/
    CreateProduct.cs
    GetProducts.cs
    ProductsModule.cs

Each feature folder contains:

• One file per use case (command/query + handler + validator)
• One Carter module for routing all endpoints in that domain

Everything for orders lives in Features/Orders/. No jumping between Controllers, Services, Models, and Repositories folders.

Route Groups and Common Configuration

Carter modules support route groups with shared configuration:

public class OrdersModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders")
            .WithTags("Orders")
            .RequireAuthorization();

        group.MapPost("", HandlePlaceOrder);
        group.MapGet("{id:guid}", HandleGetOrder);
        group.MapDelete("{id:guid}", HandleCancelOrder)
            .RequireAuthorization("Admin");
    }

    private static async Task<IResult> HandlePlaceOrder(
        PlaceOrder.Command command,
        ISender sender,
        CancellationToken ct)
    {
        var result = await sender.Send(command, ct);
        return result.IsSuccess
            ? Results.Created($"/api/orders/{result.Value}", result.Value)
            : result.ToProblemDetails();
    }

    private static async Task<IResult> HandleGetOrder(
        Guid id,
        ISender sender,
        CancellationToken ct)
    {
        var result = await sender.Send(new GetOrder.Query(id), ct);
        return result.IsSuccess
            ? Results.Ok(result.Value)
            : result.ToProblemDetails();
    }

    private static async Task<IResult> HandleCancelOrder(
        Guid id,
        ISender sender,
        CancellationToken ct)
    {
        var result = await sender.Send(new CancelOrder.Command(id), ct);
        return result.IsSuccess
            ? Results.NoContent()
            : result.ToProblemDetails();
    }
}

Extract handler methods to keep AddRoutes readable.

Endpoint Filters

If you'd rather handle cross-cutting concerns at the HTTP boundary instead of inside the MediatR pipeline, use endpoint filters. Here's a validation filter that resolves the slice's FluentValidation validator from DI:

public class ValidationFilter<TRequest> : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var request = context.Arguments
            .OfType<TRequest>()
            .FirstOrDefault();

        if (request is null)
        {
            return await next(context);
        }

        var validator = context.HttpContext.RequestServices
            .GetService<IValidator<TRequest>>();

        if (validator is not null)
        {
            var result = await validator.ValidateAsync(request);
            if (!result.IsValid)
            {
                return Results.ValidationProblem(result.ToDictionary());
            }
        }

        return await next(context);
    }
}

The filter is generic over the request type, so you apply it per endpoint:

group.MapPost("", HandlePlaceOrder)
    .AddEndpointFilter<ValidationFilter<PlaceOrder.Command>>();

Pick one place to validate (pipeline behavior or endpoint filter), not both.

Testing Carter Modules

Because Carter modules are just Minimal API routes, they test like any other endpoint through WebApplicationFactory:

public class OrdersModuleTests
    : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public OrdersModuleTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task PlaceOrder_WithInvalidBody_ReturnsProblemDetails()
    {
        var response = await _client.PostAsJsonAsync("/api/orders", new
        {
            CustomerId = Guid.Empty,
            Items = Array.Empty<object>()
        });

        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
    }
}

MapCarter() runs during test host startup, so all modules are discovered exactly as in production. No special test setup for Carter itself.

Why Carter + VSA Works

What the combination buys you:

• Auto-discovery: Carter finds modules automatically, no manual registration in Program.cs
• Feature isolation: each module encapsulates a bounded set of endpoints
• Clean Program.cs: just app.MapCarter() instead of dozens of MapGet/MapPost calls
• Route grouping: share authorization, filters, and tags across related endpoints
• Testability: each handler is independent and easily unit-tested

Carter vs. Plain Minimal APIs

Without Carter, endpoints pile up in Program.cs or require manual extension methods:

// Without Carter - gets messy fast
app.MapPost("/api/orders", HandlePlaceOrder);
app.MapGet("/api/orders/{id}", HandleGetOrder);
app.MapGet("/api/orders", HandleGetOrders);
app.MapPost("/api/customers", HandleRegisterCustomer);
app.MapGet("/api/customers/{id}", HandleGetCustomer);
// ... 50 more lines

With Carter, each module owns its routes. Program.cs stays clean.

To be fair, Carter isn't the only way to get there. You can build the same auto-discovery yourself with an IEndpoint interface and assembly scanning, which I showed in automatically registering Minimal APIs. Choose Carter if you want the convention ready-made and don't mind a third-party dependency in your API layer; roll your own if you'd rather own those 30 lines of reflection.

Summary

Carter doesn't change what a vertical slice is. It standardizes how a slice exposes its routes: each feature folder gets a module, each module owns its endpoints, and Program.cs shrinks to app.MapCarter().

If you want that convention ready-made, use Carter. If you'd rather avoid the dependency, the IEndpoint approach gets you the same result for 30 lines of your own code. Either way, if you're building with Minimal APIs and vertical slices, the endpoints should end up where they belong: inside the slice.

Thanks for reading, and stay awesome!

Where Does Validation Go?

In Vertical Slice Architecture, each feature is self-contained. The validator lives next to the handler - not in a separate "Validators" folder across the project.

Features/
  Orders/
    PlaceOrder.cs        ← Command + Handler + Validator
    GetOrder.cs
    CancelOrder.cs

The Validator

Use FluentValidation to define rules:

public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId,
        List<OrderItemRequest> Items) : IRequest<Result<Guid>>;

    public sealed record OrderItemRequest(
        Guid ProductId,
        int Quantity,
        decimal UnitPrice);

    public sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.CustomerId)
                .NotEmpty()
                .WithMessage("Customer ID is required.");

            RuleFor(x => x.Items)
                .NotEmpty()
                .WithMessage("At least one item is required.");

            RuleForEach(x => x.Items).ChildRules(item =>
            {
                item.RuleFor(x => x.ProductId).NotEmpty();
                item.RuleFor(x => x.Quantity)
                    .GreaterThan(0)
                    .WithMessage("Quantity must be positive.");
                item.RuleFor(x => x.UnitPrice)
                    .GreaterThan(0)
                    .WithMessage("Price must be positive.");
            });
        }
    }

    public sealed class Handler : IRequestHandler<Command, Result<Guid>>
    {
        private readonly ApplicationDbContext _db;

        public Handler(ApplicationDbContext db) => _db = db;

        public async Task<Result<Guid>> Handle(
            Command request, CancellationToken ct)
        {
            // No input validation here - the pipeline already ran it
            var order = Order.Create(request.CustomerId, request.Items);

            _db.Orders.Add(order);
            await _db.SaveChangesAsync(ct);

            return order.Id;
        }
    }
}

The command, validator, and handler are all in one file. Everything about "Place Order" is in one place.

Automatic Validation With a Pipeline Behavior

Instead of calling the validator manually in every handler, use a MediatR pipeline behavior. This is the same approach I showed for CQRS validation with MediatR and FluentValidation:

public sealed class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(
        IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
            return await next();

        var context = new ValidationContext<TRequest>(request);

        var validationResults = await Task.WhenAll(
            _validators.Select(v => v.ValidateAsync(context, ct)));

        var failures = validationResults
            .SelectMany(r => r.Errors)
            .Where(f => f is not null)
            .ToList();

        if (failures.Count != 0)
            throw new ValidationException(failures);

        return await next();
    }
}

Register it:

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddOpenBehavior(typeof(ValidationBehavior<,>));
});

builder.Services.AddValidatorsFromAssembly(
    typeof(Program).Assembly);

Every request that has a matching IValidator<T> is validated automatically before reaching the handler. Pair this throwing variant with a global exception handler that turns ValidationException into a 400 Problem Details response.

Result-Based Validation

Instead of throwing exceptions, return validation errors as a Result:

public sealed class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
    where TResponse : Result
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(
        IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
            return await next();

        var context = new ValidationContext<TRequest>(request);

        var validationResults = await Task.WhenAll(
            _validators.Select(v => v.ValidateAsync(context, ct)));

        var errors = validationResults
            .SelectMany(r => r.Errors)
            .Where(f => f is not null)
            .Select(f => new Error(f.PropertyName, f.ErrorMessage))
            .ToArray();

        if (errors.Length != 0)
            return (TResponse)(object)Result.Failure(
                new ValidationError(errors));

        return await next();
    }
}

The handler never runs if validation fails. The endpoint returns a 400 response with the validation errors.

One wrinkle to be aware of: the cast at the end only works when TResponse is the non-generic Result. For handlers returning Result<T>, a complete implementation creates the typed failure through a static factory or a small piece of reflection. It's a one-time cost in the behavior, and every slice benefits.

Input Validation vs Domain Validation

There are two layers of validation in any application:

Input validation (FluentValidation) - checks data format and presence:

• Is the email format valid?
• Is the quantity positive?
• Is the required field present?

Domain validation (domain invariants) - checks business rules:

• Can this customer place an order?
• Is this product in stock?
• Does the discount code apply?

// Input validation (FluentValidation) - runs BEFORE the handler
public sealed class Validator : AbstractValidator<Command>
{
    public Validator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(x => x.ProductId).NotEmpty();
            item.RuleFor(x => x.Quantity).GreaterThan(0);
        });
    }
}

// Domain validation - runs INSIDE the handler
public sealed class Handler : IRequestHandler<Command, Result<Guid>>
{
    private readonly ApplicationDbContext _db;

    public Handler(ApplicationDbContext db) => _db = db;

    public async Task<Result<Guid>> Handle(
        Command request, CancellationToken ct)
    {
        var productIds = request.Items.Select(i => i.ProductId).ToList();

        var products = await _db.Products
            .Where(p => productIds.Contains(p.Id))
            .ToDictionaryAsync(p => p.Id, ct);

        foreach (var item in request.Items)
        {
            if (!products.TryGetValue(item.ProductId, out var product))
                return Result.Failure<Guid>(ProductErrors.NotFound);

            if (product.StockQuantity < item.Quantity)
                return Result.Failure<Guid>(ProductErrors.InsufficientStock);
        }

        // Domain checks passed - create the order
        var order = Order.Create(request.CustomerId, request.Items);

        _db.Orders.Add(order);
        await _db.SaveChangesAsync(ct);

        return order.Id;
    }
}

Input validation rejects obviously bad data. Domain validation enforces business rules.

Async Validators

Some validation requires database access:

public sealed class Validator : AbstractValidator<Command>
{
    public Validator(ApplicationDbContext db)
    {
        RuleFor(x => x.Email)
            .NotEmpty()
            .EmailAddress()
            .MustAsync(async (email, ct) =>
                !await db.Users.AnyAsync(u => u.Email == email, ct))
            .WithMessage("Email is already registered.");
    }
}

Use async validators sparingly. Most input validation should be synchronous. Save database checks for the handler when possible.

Testing Your Validators

Co-located validators are trivially testable with FluentValidation's built-in TestHelper:

public class PlaceOrderValidatorTests
{
    private readonly PlaceOrder.Validator _validator = new();

    [Fact]
    public void Should_Fail_When_Items_Are_Empty()
    {
        var command = new PlaceOrder.Command(Guid.NewGuid(), []);

        var result = _validator.TestValidate(command);

        result.ShouldHaveValidationErrorFor(x => x.Items);
    }

    [Fact]
    public void Should_Pass_For_Valid_Command()
    {
        var command = new PlaceOrder.Command(
            Guid.NewGuid(),
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 2, 10m)]);

        var result = _validator.TestValidate(command);

        result.ShouldNotHaveAnyValidationErrors();
    }
}

TestValidate gives you assertion helpers that point at the exact rule that failed. These tests run in microseconds, so cover every rule. More on the broader strategy in testing vertical slices.

Endpoint Error Mapping

Map validation errors to Problem Details:

app.MapPost("/api/orders", async (
    PlaceOrder.Command command,
    ISender sender) =>
{
    var result = await sender.Send(command);

    return result.Match(
        onSuccess: id => Results.Created($"/api/orders/{id}", id),
        onFailure: error => error switch
        {
            ValidationError ve => Results.ValidationProblem(
                ve.Errors.GroupBy(e => e.Code)
                    .ToDictionary(
                        g => g.Key,
                        g => g.Select(e => e.Description).ToArray())),
            _ => Results.Problem(
                detail: error.Description,
                statusCode: StatusCodes.Status400BadRequest)
        });
});

Summary

Validation in Vertical Slice Architecture:

1. Co-locate validators with features - same file as the command and handler
2. Pipeline behavior validates automatically before the handler runs
3. Input validation (format, presence) goes in FluentValidation
4. Domain validation (business rules) stays in the handler or domain model
5. Throw or return Results - both work, pick one convention and stay consistent
6. Map to Problem Details for consistent API error responses

Validation is a cross-cutting concern - handle it once in the pipeline, not in every handler.

Thanks for reading, and stay awesome!

Layered architectures produce layered tests: repository tests, service tests, controller tests, and a mock for every seam between them. Vertical slices collapse those seams, so the tests change shape too.

Testing Slices, Not Layers

In Vertical Slice Architecture, each feature is self-contained - request, handler, validation, persistence. This means your tests should be organized by feature, not by layer.

Instead of:

• OrderRepositoryTests
• OrderServiceTests
• OrderControllerTests

You write:

• PlaceOrderTests
• GetOrderTests
• CancelOrderTests

Each test covers one slice from input to output.

Unit Testing a Handler

The simplest test targets the handler directly:

public class PlaceOrderTests
{
    private readonly ApplicationDbContext _db;
    private readonly PlaceOrder.Handler _handler;

    public PlaceOrderTests()
    {
        _db = CreateInMemoryDbContext();
        _handler = new PlaceOrder.Handler(_db);
    }

    [Fact]
    public async Task Should_Create_Order_With_Valid_Request()
    {
        // Arrange
        var customer = new Customer { Id = Guid.NewGuid(), Name = "John" };
        _db.Customers.Add(customer);
        await _db.SaveChangesAsync();

        var command = new PlaceOrder.Command(
            customer.Id,
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 2)]);

        // Act
        var result = await _handler.Handle(command, CancellationToken.None);

        // Assert
        result.IsSuccess.Should().BeTrue();
        var order = await _db.Orders.FirstAsync();
        order.CustomerId.Should().Be(customer.Id);
        order.Items.Should().HaveCount(1);
    }

    [Fact]
    public async Task Should_Fail_When_Customer_Not_Found()
    {
        var command = new PlaceOrder.Command(
            Guid.NewGuid(),
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 1)]);

        var result = await _handler.Handle(command, CancellationToken.None);

        result.IsSuccess.Should().BeFalse();
        result.Error.Code.Should().Be("Customer.NotFound");
    }

    private static ApplicationDbContext CreateInMemoryDbContext()
    {
        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
            .UseInMemoryDatabase(Guid.NewGuid().ToString())
            .Options;

        return new ApplicationDbContext(options);
    }
}

This tests business logic without HTTP, serialization, or middleware.

One caveat: the in-memory DbContext keeps these tests fast, but it doesn't enforce constraints or translate real SQL. That's an acceptable trade for handler logic tests. For query-heavy slices, prefer the Testcontainers approach below (I compare the options in testing EF Core repositories).

Testing Validation

Test validators separately - they're fast and don't need infrastructure:

public class PlaceOrderValidatorTests
{
    private readonly PlaceOrder.Validator _validator = new();

    [Fact]
    public void Should_Fail_When_CustomerId_Is_Empty()
    {
        var command = new PlaceOrder.Command(
            Guid.Empty,
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 1)]);

        var result = _validator.Validate(command);

        result.IsValid.Should().BeFalse();
        result.Errors.Should().Contain(e =>
            e.PropertyName == nameof(PlaceOrder.Command.CustomerId));
    }

    [Fact]
    public void Should_Fail_When_Items_Empty()
    {
        var command = new PlaceOrder.Command(Guid.NewGuid(), []);

        var result = _validator.Validate(command);

        result.IsValid.Should().BeFalse();
    }

    [Fact]
    public void Should_Pass_With_Valid_Command()
    {
        var command = new PlaceOrder.Command(
            Guid.NewGuid(),
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 3)]);

        var result = _validator.Validate(command);

        result.IsValid.Should().BeTrue();
    }
}

Integration Testing With WebApplicationFactory

For end-to-end slice testing, use WebApplicationFactory:

public class PlaceOrderEndpointTests
    : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    private readonly HttpClient _client;

    public PlaceOrderEndpointTests(
        WebApplicationFactory<Program> factory)
    {
        _factory = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureServices(services =>
            {
                // Replace real DB with test container or in-memory
                services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
                services.AddDbContext<ApplicationDbContext>(options =>
                    options.UseInMemoryDatabase("test"));
            });
        });

        _client = _factory.CreateClient();
    }

    [Fact]
    public async Task PlaceOrder_Returns_Created()
    {
        // The handler rejects unknown customers, so seed one first
        var customerId = await SeedCustomerAsync();

        var request = new
        {
            CustomerId = customerId,
            Items = new[]
            {
                new { ProductId = Guid.NewGuid(), Quantity = 2 }
            }
        };

        var response = await _client.PostAsJsonAsync(
            "/api/orders", request);

        response.StatusCode.Should().Be(HttpStatusCode.Created);
    }

    [Fact]
    public async Task PlaceOrder_Returns_BadRequest_For_Empty_Items()
    {
        var request = new
        {
            CustomerId = Guid.NewGuid(),
            Items = Array.Empty<object>()
        };

        var response = await _client.PostAsJsonAsync(
            "/api/orders", request);

        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
    }

    private async Task<Guid> SeedCustomerAsync()
    {
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();

        var customer = new Customer { Id = Guid.NewGuid(), Name = "Test" };
        db.Customers.Add(customer);
        await db.SaveChangesAsync();

        return customer.Id;
    }
}

This tests the full HTTP pipeline - routing, model binding, validation, handler, persistence, and response serialization.

Integration Testing With Testcontainers

For realistic tests against a real database, use Testcontainers:

public class OrderApiTests : IAsyncLifetime
{
    private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
        .WithImage("postgres:16-alpine")
        .Build();

    private WebApplicationFactory<Program> _factory = null!;
    private HttpClient _client = null!;

    public async Task InitializeAsync()
    {
        await _postgres.StartAsync();

        _factory = new WebApplicationFactory<Program>()
            .WithWebHostBuilder(builder =>
            {
                builder.ConfigureServices(services =>
                {
                    services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
                    services.AddDbContext<ApplicationDbContext>(options =>
                        options.UseNpgsql(_postgres.GetConnectionString()));
                });
            });

        _client = _factory.CreateClient();

        // Apply migrations
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();
        await db.Database.MigrateAsync();
    }

    [Fact]
    public async Task Full_Order_Lifecycle()
    {
        var customerId = await SeedCustomerAsync();

        // Place order
        var placeResponse = await _client.PostAsJsonAsync(
            "/api/orders",
            new
            {
                CustomerId = customerId,
                Items = new[]
                {
                    new { ProductId = Guid.NewGuid(), Quantity = 2 }
                }
            });
        placeResponse.StatusCode.Should().Be(HttpStatusCode.Created);

        var orderId = await placeResponse.Content
            .ReadFromJsonAsync<Guid>();

        // Get order
        var getResponse = await _client.GetAsync(
            $"/api/orders/{orderId}");
        getResponse.StatusCode.Should().Be(HttpStatusCode.OK);

        // Cancel order
        var cancelResponse = await _client.DeleteAsync(
            $"/api/orders/{orderId}");
        cancelResponse.StatusCode.Should().Be(HttpStatusCode.NoContent);
    }

    private async Task<Guid> SeedCustomerAsync()
    {
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();

        var customer = new Customer { Id = Guid.NewGuid(), Name = "Test" };
        db.Customers.Add(customer);
        await db.SaveChangesAsync();

        return customer.Id;
    }

    public async Task DisposeAsync()
    {
        await _factory.DisposeAsync();
        await _postgres.DisposeAsync();
    }
}

Where Mocks Still Fit

Slices reduce the need for mocking, but they don't eliminate it. External systems (payment gateways, email providers, third-party APIs) should still be replaced with test doubles, even in integration tests:

var factory = new WebApplicationFactory<Program>()
    .WithWebHostBuilder(builder =>
    {
        builder.ConfigureTestServices(services =>
        {
            services.RemoveAll<IPaymentGateway>();
            services.AddScoped<IPaymentGateway, FakePaymentGateway>();
        });
    });

The rule I follow: fake what you don't own (external services), keep what you do own (your database, your handlers, your validation) real. That way a passing slice test means the feature genuinely works, minus only the third-party call you can't control anyway.

Guarding Slice Independence

One more test category worth having: a few architecture tests that keep slices from quietly coupling to each other. A PlaceOrder handler reaching into Features.Shipping internals is exactly the kind of erosion that's invisible in code review. I cover the setup in architecture testing in .NET; two or three rules per feature group are enough.

Test Organization

Mirror the feature structure:

Features/
  Orders/
    PlaceOrder.cs
    GetOrder.cs
    CancelOrder.cs
tests/
  Features/
    Orders/
      PlaceOrderTests.cs
      PlaceOrderValidatorTests.cs
      GetOrderTests.cs
      CancelOrderTests.cs

Each test file tests one slice. Finding the tests for a feature is trivial.

What to Test at Each Level

Three levels, each with a distinct job:

• Validator tests: input validation rules. Pure logic, run in microseconds.
• Handler unit tests: business logic in isolation. Fast, no HTTP.
• Integration tests: the full HTTP pipeline against a real database. Slower, but they prove the slice actually works.

Because a slice is a complete feature, integration tests here carry more weight than in layered architectures. Don't be afraid to have plenty of them; that's what I do instead of the classic test pyramid. A slice test that goes HTTP-to-database catches serialization bugs, validation wiring, and query errors in one shot.

Summary

Testing vertical slices in .NET:

1. Organize tests by feature, not by layer
2. Unit test handlers with in-memory DbContext for fast feedback
3. Unit test validators separately - they're pure logic
4. Integration test with WebApplicationFactory for full HTTP pipeline
5. Use Testcontainers for realistic database tests
6. Lean on integration tests - a slice test proves the whole feature works

Each slice is independently testable. That's the power of vertical slices.

Thanks for reading, and stay awesome!

Open almost any .NET solution and you can guess the top-level folders before it loads: Controllers, Services, Models. That structure tells you which framework the team used, but nothing about what the application does.

The Problem With Layer-Based Organization

Most .NET projects start like this:

Controllers/
    OrdersController.cs
    CustomersController.cs
    ProductsController.cs
Services/
    OrderService.cs
    CustomerService.cs
    ProductService.cs
Models/
    Order.cs
    Customer.cs
    Product.cs
DTOs/
    OrderRequest.cs
    OrderResponse.cs
    CustomerRequest.cs
Validators/
    OrderValidator.cs
    CustomerValidator.cs

To work on one feature (placing an order), you touch files in 5+ folders. To understand a feature, you jump between directories piecing together how OrdersController calls OrderService which uses Order and OrderRequest.

This is organizing by layer - it groups files by what they are (controller, service, model), not by what they do.

Feature Folders: Organize by What Code Does

Feature folders flip the structure. Everything related to a feature lives together:

Features/
    Orders/
        PlaceOrder/
            PlaceOrderEndpoint.cs
            PlaceOrderCommand.cs
            PlaceOrderCommandHandler.cs
            PlaceOrderRequest.cs
            PlaceOrderResponse.cs
            PlaceOrderValidator.cs
        CancelOrder/
            CancelOrderEndpoint.cs
            CancelOrderCommand.cs
            CancelOrderCommandHandler.cs
        GetOrderById/
            GetOrderByIdEndpoint.cs
            GetOrderByIdQuery.cs
            GetOrderByIdQueryHandler.cs
            OrderResponse.cs
    Customers/
        RegisterCustomer/
            RegisterCustomerEndpoint.cs
            RegisterCustomerCommand.cs
            RegisterCustomerCommandHandler.cs
        GetCustomer/
            GetCustomerEndpoint.cs
            GetCustomerQuery.cs

To work on "Place Order," you open one folder. Everything is there. No jumping between directories.

This is how Vertical Slice Architecture and Screaming Architecture naturally organize code.

Implementing Feature Folders

Step 1: Create the Feature Structure

Each feature gets its own folder with everything it needs:

// Features/Orders/PlaceOrder/PlaceOrderCommand.cs
public sealed record PlaceOrderCommand(
    Guid CustomerId,
    List<OrderItemRequest> Items) : ICommand<Guid>;

// Features/Orders/PlaceOrder/PlaceOrderCommandHandler.cs
public sealed class PlaceOrderCommandHandler(
    IOrderRepository orderRepository,
    IUnitOfWork unitOfWork)
    : ICommandHandler<PlaceOrderCommand, Guid>
{
    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);
        orderRepository.Add(order);
        await unitOfWork.SaveChangesAsync(ct);
        return order.Id;
    }
}

// Features/Orders/PlaceOrder/PlaceOrderEndpoint.cs
public static class PlaceOrderEndpoint
{
    public static void Map(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/orders", async (
            PlaceOrderRequest request,
            ICommandHandler<PlaceOrderCommand, Guid> handler,
            CancellationToken ct) =>
        {
            var command = new PlaceOrderCommand(request.CustomerId, request.Items);
            var result = await handler.Handle(command, ct);

            return result.IsSuccess
                ? Results.Created($"/api/orders/{result.Value}", result.Value)
                : result.ToProblemDetails();
        });
    }
}

// Features/Orders/PlaceOrder/PlaceOrderValidator.cs
public sealed class PlaceOrderValidator : AbstractValidator<PlaceOrderCommand>
{
    public PlaceOrderValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
    }
}

The ICommand and ICommandHandler abstractions are the thin CQRS interfaces I defined in CQRS Pattern: The Way It Should Have Been From the Start.

Step 2: Auto-Register Endpoints

Scan for all endpoint classes and register them:

public static class EndpointRegistration
{
    public static void MapFeatureEndpoints(this IEndpointRouteBuilder app)
    {
        var endpointTypes = typeof(Program).Assembly
            .GetTypes()
            .Where(t => t.GetMethods(BindingFlags.Public | BindingFlags.Static)
                .Any(m => m.Name == "Map" &&
                    m.GetParameters().Length == 1 &&
                    m.GetParameters()[0].ParameterType == typeof(IEndpointRouteBuilder)));

        foreach (var type in endpointTypes)
        {
            var method = type.GetMethod("Map",
                BindingFlags.Public | BindingFlags.Static,
                [typeof(IEndpointRouteBuilder)]);

            method?.Invoke(null, [app]);
        }
    }
}

// Program.cs
app.MapFeatureEndpoints();

Step 3: Register Handlers

Use assembly scanning with the Scrutor library, so a new slice never means editing Program.cs:

dotnet add package Scrutor

builder.Services.Scan(scan => scan
    .FromAssemblyOf<PlaceOrderCommandHandler>()
    .AddClasses(c => c.AssignableTo(typeof(ICommandHandler<,>)))
    .AsImplementedInterfaces()
    .WithScopedLifetime()
    .AddClasses(c => c.AssignableTo(typeof(IQueryHandler<,>)))
    .AsImplementedInterfaces()
    .WithScopedLifetime());

One File or One Folder per Feature?

There are two popular granularities, and both are fine:

Folder per operation (shown above): PlaceOrder/ contains five or six small files. Best when slices carry validators, mappers, and multiple DTOs.

Single file per operation: the whole slice lives in PlaceOrder.cs as a static class with nested types:

// Features/Orders/PlaceOrder.cs
public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId, List<OrderItemRequest> Items) : ICommand<Guid>;

    public sealed class Validator : AbstractValidator<Command> { /* ... */ }

    internal sealed class Handler : ICommandHandler<Command, Guid> { /* ... */ }

    public static void Map(IEndpointRouteBuilder app) { /* ... */ }
}

The single-file style keeps the entire feature on one screen and makes names collision-free (PlaceOrder.Command, CancelOrder.Command). The static Map method keeps the same shape as before, so the endpoint scanner from Step 2 picks it up unchanged. It's the style I lean toward for small-to-medium slices, and I've written more about structuring vertical slices if you want the full reasoning.

Start with one file. Split into a folder when the file gets uncomfortable to scroll.

Feature Folders in Clean Architecture

You can combine feature folders with Clean Architecture:

src/
  MyApp.Domain/
    Orders/
      Order.cs
      OrderLineItem.cs
      IOrderRepository.cs
    Customers/
      Customer.cs
  MyApp.Application/
    Orders/
      PlaceOrder/
        PlaceOrderCommand.cs
        PlaceOrderCommandHandler.cs
        PlaceOrderValidator.cs
      CancelOrder/
        CancelOrderCommand.cs
        CancelOrderCommandHandler.cs
      GetOrderById/
        GetOrderByIdQuery.cs
        GetOrderByIdQueryHandler.cs
        OrderResponse.cs
  MyApp.Infrastructure/
    Persistence/
      Repositories/
        OrderRepository.cs
  MyApp.Api/
    Endpoints/
      Orders/
        PlaceOrderEndpoint.cs
        CancelOrderEndpoint.cs
        GetOrderByIdEndpoint.cs

The Application layer uses feature folders. The Domain layer groups entities by aggregate. The Presentation layer mirrors the Application structure.

When to Use Feature Folders

Feature folders work well when:

• Features are relatively independent
• The team works on features, not layers
• You want code locality (related code close together)
• You're using CQRS (commands and queries naturally form features)

Stick with layers when:

• There's extensive code sharing between features
• The project is very small (5-10 files total)
• Your team is more comfortable with the traditional structure

Shared Code

Some code is truly shared - domain entities, base classes, common helpers. Put these in a Common or Shared folder:

Features/
    Orders/
        PlaceOrder/...
        CancelOrder/...
    Customers/...
Common/
    Domain/
        Entity.cs
        ValueObject.cs
        AggregateRoot.cs
    Results/
        Result.cs
        Error.cs

Keep the shared folder minimal. If code is only used by one feature, it belongs in that feature's folder. When two features start needing the same logic, resist the reflex to abstract immediately; I've written about where shared logic should live, and the short answer is: extract when the duplication hurts, not when it merely exists.

Migrating an Existing Codebase

You don't need a rewrite to adopt feature folders. The incremental path:

1. Create the Features folder next to your existing Controllers/Services folders.
2. Move one feature end to end. Pick a small, actively developed one. Pull its controller action, service method, DTOs, and validator into a feature folder, collapsing the service and repository indirection where it adds nothing.
3. Ship it. The old layers and the new folder coexist fine; routing doesn't care where files live.
4. Repeat opportunistically. Migrate features when you touch them for other reasons. Untouched code stays where it is.

The biggest friction is usually psychological, not technical: the codebase looks "inconsistent" during the transition. That's fine. A consistent structure that hides features is worse than a mixed one that's converging on clarity.

Summary

Feature folders organize code by business capability instead of technical concern. Every file related to placing an order lives in the PlaceOrder folder.

The result: faster navigation, fewer merge conflicts, and code that screams what the application does.

Stop grouping by layer. Start grouping by feature.

Thanks for reading, and stay awesome!

The Duplication Problem

In Vertical Slice Architecture, each feature is self-contained. Cross-cutting concerns are the behaviors that cut across every slice: validation, logging, caching, authorization, transaction management.

You don't want to copy-paste these into every handler. That would defeat the purpose. And this question is really a special case of a broader one I keep coming back to: where does the shared logic live in a sliced codebase?

MediatR Pipeline Behaviors

The most common solution is MediatR pipeline behaviors. They wrap every request handler automatically.

Validation Behavior

Validate every command before the handler executes:

public class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
        {
            return await next();
        }

        var context = new ValidationContext<TRequest>(request);

        var failures = _validators
            .Select(v => v.Validate(context))
            .SelectMany(r => r.Errors)
            .Where(f => f is not null)
            .ToList();

        if (failures.Count != 0)
        {
            throw new ValidationException(failures);
        }

        return await next();
    }
}

Each slice just defines a validator:

// Features/Orders/PlaceOrder.cs
public sealed class Validator : AbstractValidator<Command>
{
    public Validator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
    }
}

The behavior picks it up automatically - zero wiring per slice.

Logging Behavior

Log every request entry, exit, and duration:

public class LoggingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public LoggingBehavior(
        ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    {
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var requestName = typeof(TRequest).Name;
        _logger.LogInformation("Handling {RequestName}", requestName);

        var sw = Stopwatch.StartNew();
        var response = await next();
        sw.Stop();

        _logger.LogInformation(
            "Handled {RequestName} in {ElapsedMs}ms",
            requestName, sw.ElapsedMilliseconds);

        return response;
    }
}

Transaction Behavior

Wrap commands in a database transaction. The ICommand constraint uses the marker interface from combining vertical slices with CQRS:

public class TransactionBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ICommand<TResponse>
{
    private readonly ApplicationDbContext _db;

    public TransactionBehavior(ApplicationDbContext db)
    {
        _db = db;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        await using var transaction =
            await _db.Database.BeginTransactionAsync(ct);

        try
        {
            var response = await next();
            await transaction.CommitAsync(ct);
            return response;
        }
        catch
        {
            await transaction.RollbackAsync(ct);
            throw;
        }
    }
}

Notice the constraint ICommand<TResponse> - this behavior only wraps commands, not queries. Queries don't need transactions.

Caching Behavior

Cache query results:

public interface ICacheable
{
    string CacheKey { get; }
    TimeSpan? Expiration { get; }
}

public class CachingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>, ICacheable
{
    private readonly IDistributedCache _cache;

    public CachingBehavior(IDistributedCache cache)
    {
        _cache = cache;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var cachedResult = await _cache.GetStringAsync(request.CacheKey, ct);
        if (cachedResult is not null)
        {
            return JsonSerializer.Deserialize<TResponse>(cachedResult)!;
        }

        var response = await next();

        await _cache.SetStringAsync(
            request.CacheKey,
            JsonSerializer.Serialize(response),
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow =
                    request.Expiration ?? TimeSpan.FromMinutes(5)
            },
            ct);

        return response;
    }
}

Opt in per query:

public sealed record Query(Guid Id)
    : IRequest<ProductResponse>, ICacheable
{
    public string CacheKey => $"product-{Id}";
    public TimeSpan? Expiration => TimeSpan.FromMinutes(10);
}

Only queries that implement ICacheable get cached. The behavior ignores everything else.

Registration

Register all behaviors in order:

services.AddMediatR(config =>
{
    config.RegisterServicesFromAssembly(typeof(Program).Assembly);
    config.AddOpenBehavior(typeof(LoggingBehavior<,>));
    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
    config.AddOpenBehavior(typeof(TransactionBehavior<,>));
    config.AddOpenBehavior(typeof(CachingBehavior<,>));
});

Order matters. Logging wraps validation, which wraps transaction, which wraps caching.

Pitfalls to Watch For

A few ways this setup bites in practice:

• Behavior order bugs are silent. If you register CachingBehavior before TransactionBehavior, a cached response can be returned without the transaction ever opening - which is correct for queries but masks a misconfigured command that accidentally implements ICacheable. Review the registration order whenever you add a behavior.
• Caching failures, not just successes. The caching behavior above serializes whatever the handler returns, including a failed Result. Add a check so only successful responses get cached, or you'll serve a cached error for ten minutes.
• Transactions around everything. Wrapping every command in an explicit transaction is redundant when the handler makes a single SaveChangesAsync call (EF Core already wraps that in a transaction). Reserve the transaction behavior for handlers that perform multiple save operations.
• Behavior sprawl. Every behavior runs on every matching request. Ten behaviors deep, debugging a request means stepping through ten wrappers. Keep the pipeline short and boring.

Can You Handle Cross-Cutting Concerns Without MediatR?

If you've moved off MediatR (or never adopted it), the same pattern works as decorators over your own handler interfaces. Define ICommandHandler<TCommand, TResponse>, then register decorators (Scrutor's Decorate makes this one line per behavior). The mechanics change; the idea (cross-cutting logic wraps the handler, slices stay clean) doesn't.

Endpoint Filters (Alternative)

If you prefer not to use MediatR, ASP.NET Core endpoint filters handle cross-cutting concerns at the HTTP layer:

public class ValidationFilter<TRequest> : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var request = context.Arguments
            .OfType<TRequest>()
            .FirstOrDefault();

        if (request is null)
        {
            return await next(context);
        }

        var validator = context.HttpContext.RequestServices
            .GetService<IValidator<TRequest>>();

        if (validator is not null)
        {
            var result = await validator.ValidateAsync(request);
            if (!result.IsValid)
            {
                return Results.ValidationProblem(
                    result.ToDictionary());
            }
        }

        return await next(context);
    }
}

Base Handler Classes (Use Sparingly)

Another option - a base class for shared handler logic:

public abstract class BaseHandler
{
    protected readonly ApplicationDbContext Db;
    protected readonly ICurrentUserService CurrentUser;

    protected BaseHandler(
        ApplicationDbContext db,
        ICurrentUserService currentUser)
    {
        Db = db;
        CurrentUser = currentUser;
    }
}

I generally avoid this. It creates coupling and makes the inheritance hierarchy grow. Pipeline behaviors are more flexible.

The Pattern Summary

Here's the mapping I use, concern by concern:

• Validation: pipeline behavior + FluentValidation. Applies to every request that has a validator; slices without one pass through untouched.
• Logging: pipeline behavior. Applies to all requests.
• Transactions: pipeline behavior constrained to ICommand. Write operations only.
• Caching: pipeline behavior + ICacheable marker. Opt-in per query.
• Authorization: pipeline behavior or endpoint filter, declared per request.
• Error handling: a global exception handler at the HTTP boundary, so handlers never need try-catch blocks for presentation concerns.

Summary

Cross-cutting concerns in Vertical Slice Architecture are solved with:

1. Pipeline behaviors - wrap every handler automatically
2. Marker interfaces - opt in to specific behaviors (ICacheable, ICommand)
3. Endpoint filters - HTTP-level concerns
4. Convention over configuration - validators are discovered, not registered manually

Each slice stays focused on its feature. The pipeline handles everything else.

Thanks for reading, and stay awesome!