EF Core Mapping for DDD for Dummies

The bad one is easy for EF Core but anyone can break the rules. The good one protects itself — EF Core just needs a little help to save it.

// ❌ BAD — no rules, anyone can change anything
public class Order
{
    public Guid Id { get; set; }
    public string Status { get; set; } = "";
    public List<OrderLine> Lines { get; set; } = [];
    // Someone can write: order.Status = "Shipped" on an empty order. Oops.
}

// ✅ GOOD — rules live here, properties are protected
public sealed class Order
{
    public OrderId Id { get; private set; }
    public OrderStatus Status { get; private set; }
    private readonly List<OrderLine> _lines = [];
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

    private Order() { } // EF Core needs this empty constructor — you never call it

    public static Order Create(CustomerId customerId) { /* ... */ }
    public void AddLine(ProductId productId, int qty, Money price) { /* checks rules */ }
    public void Place() { /* checks rules before shipping */ }
}

Your Domain project (business rules) should never mention EF Core or SQL Server. All the "how to save to the database" code goes in a separate Infrastructure project. Think of it like this: your business code shouldn't know a database exists.

// Domain/Billing.Domain.csproj
//   → NO EntityFrameworkCore package. Just plain C#.

// Infrastructure/Billing.Infrastructure.csproj
//   → Has EF Core. References Domain. Contains mapping files.

// Example mapping file:
// Infrastructure/Persistence/Configurations/OrderConfiguration.cs

Domain = your business classes. Application = "do this action" handlers. Infrastructure = EF Core and mapping files. Don't mix them up.

src/
├── Billing.Domain/              # Business rules — NO EF Core here
│   ├── Orders/
│   │   ├── Order.cs             # The "boss" object (aggregate root)
│   │   ├── OrderLine.cs         # A line item inside an order
│   │   └── OrderId.cs           # A safe ID type (section 6)
│   └── Common/
│       └── Money.cs             # A small object with no ID (section 4)
│
├── Billing.Application/         # "Place order", "Cancel order" — NO EF Core
│
└── Billing.Infrastructure/      # EF Core lives HERE
    └── Persistence/
        ├── ApplicationDbContext.cs
        └── Configurations/
            └── OrderConfiguration.cs   # "How to save Order to SQL"

DbSet means "EF Core can load and save this type directly." Only the main object (like Order) gets one. Line items (OrderLine) are saved automatically when you save the order.

public sealed class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
    : DbContext(options)
{
    // ✅ YES — Order is the "boss" of its group
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();

    // ❌ NO — OrderLine is saved through Order, not on its own
    // public DbSet<OrderLine> OrderLines => ...  DON'T DO THIS

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Finds all mapping files automatically
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
    }
}

Notice: you can't change status directly. You call Place() and the class checks the rules for you.

// Domain/Orders/Order.cs
public sealed class Order : BaseEntity
{
    public OrderId Id { get; private set; }
    public CustomerId CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public Money Total { get; private set; } = Money.Zero;

    private readonly List<OrderLine> _lines = [];
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

    private Order() { } // EF Core only — your code never calls this

    public static Order Create(CustomerId customerId)
    {
        var order = new Order
        {
            Id = OrderId.New(),
            CustomerId = customerId,
            Status = OrderStatus.Draft
        };
        order.Raise(new OrderCreatedEvent(order.Id));
        return order;
    }

    public void AddLine(ProductId productId, int qty, Money unitPrice)
    {
        if (Status != OrderStatus.Draft)
            throw new DomainException("Cannot modify a placed order.");
        if (qty <= 0)
            throw new DomainException("Quantity must be positive.");

        _lines.Add(new OrderLine(productId, qty, unitPrice));
        Total = Money.Sum(_lines.Select(l => l.LineTotal));
    }

    public void Place()
    {
        if (_lines.Count == 0) throw new DomainException("Empty order.");
        Status = OrderStatus.Placed;
        Raise(new OrderPlacedEvent(Id, CustomerId, Total));
    }
}

This file lives in Infrastructure. It says: table name, how to save IDs, how to save Money, how to save line items, and what to ignore.

// Infrastructure/Persistence/Configurations/OrderConfiguration.cs
public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders");

        builder.HasKey(o => o.Id);
        builder.Property(o => o.Id)
            .HasConversion(id => id.Value, v => new OrderId(v));

        builder.Property(o => o.CustomerId)
            .HasConversion(id => id.Value, v => new CustomerId(v));

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

        // Money is a small object — save it as extra columns (section 4)
        builder.OwnsOne(o => o.Total, money =>
        {
            money.Property(m => m.Amount).HasColumnName("TotalAmount").HasPrecision(18, 2);
            money.Property(m => m.Currency).HasColumnName("TotalCurrency").HasMaxLength(3);
        });

        // Line items — saved in a separate table, linked to Order
        builder.HasMany<OrderLine>("_lines")
            .WithOne()
            .HasForeignKey(l => l.OrderId)
            .OnDelete(DeleteBehavior.Cascade);

        // Events are in-memory only — don't save to database
        builder.Ignore(o => o.DomainEvents);
    }
}

No Id property. Just data. You can add validation in the constructor — like "street can't be empty."

// Money — just amount + currency, nothing else
public sealed record Money(decimal Amount, string Currency)
{
    public static Money Zero => new(0m, "EUR");

    public static Money Sum(IEnumerable<Money> items)
    {
        var list = items.ToList();
        if (list.Count == 0) return Zero;
        return new Money(list.Sum(m => m.Amount), list[0].Currency);
    }
}

// Address — another common value object
public sealed record Address(string Street, string City, string PostalCode, string Country)
{
    public Address(string street, string city, string postalCode, string country)
    {
        if (string.IsNullOrWhiteSpace(street)) throw new DomainException("Street required.");
        Street = street.Trim();
        City = city.Trim();
        PostalCode = postalCode.Trim();
        Country = country.Trim();
    }
}

The address columns go on the Customers table — no new table needed. You pick the column names.

// Creates columns on Customers table:
//   ShipStreet, ShipCity, ShipPostalCode, ShipCountry

builder.OwnsOne(c => c.ShippingAddress, addr =>
{
    addr.Property(a => a.Street).HasColumnName("ShipStreet").HasMaxLength(200);
    addr.Property(a => a.City).HasColumnName("ShipCity").HasMaxLength(100);
    addr.Property(a => a.PostalCode).HasColumnName("ShipPostalCode").HasMaxLength(20);
    addr.Property(a => a.Country).HasColumnName("ShipCountry").HasMaxLength(60);
});

// Got more value objects on the same class? Add another OwnsOne block.

If you're on .NET 8 or later, slap [ComplexType] on the record and use ComplexProperty in the mapping. Less typing, same result.

[ComplexType]
public sealed record Money(decimal Amount, string Currency) { /* ... */ }

builder.ComplexProperty(o => o.Total, money =>
{
    money.Property(m => m.Amount).HasColumnName("TotalAmount").HasPrecision(18, 2);
    money.Property(m => m.Currency).HasColumnName("TotalCurrency").HasMaxLength(3);
});

// Which one to pick?
//   OwnsOne     → works on older EF Core, more options
//   ComplexType → .NET 8+, simpler, always extra columns

Usually one value object = extra columns. But if you have a list of them (like discount codes), EF Core creates a small separate table.

// Order has a list of discount codes (no ID on each code — value objects)

public sealed class Order : BaseEntity
{
    private readonly List<DiscountCode> _discounts = [];
    public IReadOnlyCollection<DiscountCode> Discounts => _discounts.AsReadOnly();
}

builder.OwnsMany(o => o.Discounts, d =>
{
    d.ToTable("OrderDiscounts");
    d.WithOwner().HasForeignKey("OrderId");
    d.Property(x => x.Code).HasMaxLength(20);
    d.Property(x => x.Percentage).HasPrecision(5, 2);
    d.HasKey("OrderId", nameof(DiscountCode.Code));
});

Outsiders see Lines but can't change it. Only AddLine() can add items — and it checks the rules first.

// In your Order class:
private readonly List<OrderLine> _lines = [];
public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

public void AddLine(ProductId productId, int qty, Money unitPrice)
{
    _lines.Add(new OrderLine(productId, qty, unitPrice));
}

// In your mapping file — point EF Core at "_lines"
builder.HasMany<OrderLine>("_lines")
    .WithOne()
    .HasForeignKey(l => l.OrderId)
    .OnDelete(DeleteBehavior.Cascade);

// Other way (same result):
builder.HasMany(o => o.Lines).WithOne().HasForeignKey(l => l.OrderId);
builder.Navigation(o => o.Lines)
    .UsePropertyAccessMode(PropertyAccessMode.Field)
    .HasField("_lines");

OrderLine is not the "boss." You never load it directly from the database — you load the Order and its lines come with it.

public sealed class OrderLine
{
    public OrderLineId Id { get; private set; }
    public OrderId OrderId { get; private set; }
    public ProductId ProductId { get; private set; }
    public int Quantity { get; private set; }
    public Money UnitPrice { get; private set; }
    public Money LineTotal => new(Quantity * UnitPrice.Amount, UnitPrice.Currency);

    private OrderLine() { } // EF Core only

    internal OrderLine(ProductId productId, int qty, Money unitPrice)
    {
        Id = OrderLineId.New();
        ProductId = productId;
        Quantity = qty;
        UnitPrice = unitPrice;
    }
}

// Mapping file for OrderLine
public sealed class OrderLineConfiguration : IEntityTypeConfiguration<OrderLine>
{
    public void Configure(EntityTypeBuilder<OrderLine> builder)
    {
        builder.ToTable("OrderLines");
        builder.HasKey(l => l.Id);
        builder.Property(l => l.Id)
            .HasConversion(id => id.Value, v => new OrderLineId(v));
        builder.OwnsOne(l => l.UnitPrice, m => { /* column names */ });
        builder.Ignore(l => l.LineTotal); // calculated — don't save to DB
    }
}

Each ID gets its own type. They all hold a Guid inside, but C# treats them as different things.

public readonly record struct OrderId(Guid Value)
{
    public static OrderId New() => new(Guid.NewGuid());
}

public readonly record struct CustomerId(Guid Value);
public readonly record struct ProductId(Guid Value);

// This won't compile — you swapped the IDs:
// void Ship(OrderId orderId, CustomerId customerId) { }
// Ship(customerId, orderId); // ❌ compiler error — saved you!

Write this helper once, then use one line per ID in every mapping file.

public static class StronglyTypedIdExtensions
{
    public static PropertyBuilder<TId> HasStronglyTypedIdConversion<TId>(
        this PropertyBuilder<TId> propertyBuilder)
        where TId : struct
    {
        var converter = new ValueConverter<TId, Guid>(
            id => (Guid)typeof(TId).GetProperty("Value")!.GetValue(id)!,
            value => (TId)Activator.CreateInstance(typeof(TId), value)!);

        return propertyBuilder.HasConversion(converter);
    }
}

// In OrderConfiguration — one line each:
builder.Property(o => o.Id).HasStronglyTypedIdConversion<OrderId>();
builder.Property(o => o.CustomerId).HasStronglyTypedIdConversion<CustomerId>();

Every section from this guide in one file. Use it as a template for your own entities.

public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders", schema: "billing");

        // ID
        builder.HasKey(o => o.Id);
        builder.Property(o => o.Id).HasStronglyTypedIdConversion<OrderId>();

        // Link to Customer — just store the ID, no Customer object here
        builder.Property(o => o.CustomerId).HasStronglyTypedIdConversion<CustomerId>();

        // Status as readable text in SQL ("Draft", "Placed", ...)
        builder.Property(o => o.Status)
            .HasConversion<string>()
            .HasMaxLength(32)
            .IsRequired();

        // Money value object → extra columns
        builder.OwnsOne(o => o.Total, money =>
        {
            money.Property(m => m.Amount).HasColumnName("TotalAmount").HasPrecision(18, 2);
            money.Property(m => m.Currency).HasColumnName("TotalCurrency").HasMaxLength(3);
        });

        // Line items via private _lines field
        builder.HasMany<OrderLine>("_lines")
            .WithOne()
            .HasForeignKey(l => l.OrderId)
            .OnDelete(DeleteBehavior.Cascade);

        // Don't save events to the database
        builder.Ignore(o => o.DomainEvents);

        // Speed up common searches
        builder.HasIndex(o => o.CustomerId);
        builder.HasIndex(o => o.Status);
    }
}

Simple rule: if it's about the database, it goes in Infrastructure. If it's about business rules, it stays in Domain.

// ✅ PUT in mapping file (Infrastructure):
//   • Table name
//   • How to save IDs, enums, value objects
//   • How to save lists (_lines)
//   • Ignore events and calculated properties
//   • Column sizes (MaxLength, Precision)

// ✅ OK to leave alone (EF guesses correctly):
//   • int, string, bool properties
//   • Column names same as property names

// ❌ NEVER put on Domain classes:
//   • [Table], [Column], [ForeignKey] attributes
//   • public setters "because EF needs them"
//   • Any using Microsoft.EntityFrameworkCore;

Load the order (with its lines). Call a domain method. Save. EF Core tracks what changed — you don't need an Update() method.

// Interface — only works with Order, not OrderLine
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct);
    void Add(Order order);
}

// Implementation
public sealed class OrderRepository(ApplicationDbContext db) : IOrderRepository
{
    public Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct) =>
        db.Orders
            .Include(o => o.Lines)   // don't forget this — or lines won't load!
            .FirstOrDefaultAsync(o => o.Id == id, ct);

    public void Add(Order order) => db.Orders.Add(order);
}

// Typical flow in a handler:
var order = await repo.GetByIdAsync(cmd.OrderId, ct)
    ?? throw new NotFoundException();
order.Place();                    // business rules run here
await db.SaveChangesAsync(ct);    // EF saves changes to SQL

When something important happens (order placed), the class raises an event. These live in memory until SaveChanges sends them out. Never save them as a table column.

// In mapping file — always ignore events:
builder.Ignore(o => o.DomainEvents);

// To actually send events (email, message queue, etc.)
// use an interceptor — see Clean Architecture tutorial section 8

// Main object (Order)         → DbSet + mapping file
// Item inside Order (Line)    → HasMany("_lines"), no DbSet
// Money, Address (no ID)      → OwnsOne or ComplexType
// List of small objects       → OwnsMany
// OrderId, CustomerId         → HasStronglyTypedIdConversion
// private set on property     → works fine, don't change it
// private Order() { }         → EF Core needs it, your code doesn't
// DomainEvents                → builder.Ignore(...)
// Calculated property         → builder.Ignore(...)
// Status enum                 → save as string
// Link to another aggregate   → store ID only, no Customer property