Database Mapping and EF Core📋

public class OrderRepository
{
    private readonly string _connectionString;

    public OrderRepository(string connectionString)
    {
        _connectionString = connectionString;
    }

    public async Task<Order?> GetByIdAsync(Guid id)
    {
        using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync();

        // Query 1: Get the order
        using var orderCmd = new SqlCommand(
            "SELECT Id, CustomerId, TotalAmount, CreatedDate, Status " +
            "FROM Orders WHERE Id = @Id", connection);
        orderCmd.Parameters.AddWithValue("@Id", id);

        Order? order = null;
        using (var reader = await orderCmd.ExecuteReaderAsync())
        {
            if (await reader.ReadAsync())
            {
                order = new Order
                {
                    Id = reader.GetGuid(0),
                    CustomerId = reader.GetGuid(1),
                    TotalAmount = reader.GetDecimal(2),
                    CreatedDate = reader.GetDateTime(3),
                    Status = (OrderStatus)reader.GetInt32(4)
                };
            }
        }

        if (order == null) return null;

        // Query 2: Get the line items
        using var itemsCmd = new SqlCommand(
            "SELECT Id, OrderId, ProductId, Quantity, UnitPrice " +
            "FROM LineItems WHERE OrderId = @OrderId", connection);
        itemsCmd.Parameters.AddWithValue("@OrderId", id);

        var items = new List<LineItem>();
        using (var reader = await itemsCmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                items.Add(new LineItem
                {
                    Id = reader.GetGuid(0),
                    OrderId = reader.GetGuid(1),
                    ProductId = reader.GetGuid(2),
                    Quantity = reader.GetInt32(3),
                    UnitPrice = reader.GetDecimal(4)
                });
            }
        }

        order.LineItems = items;
        return order;
    }

    public async Task AddAsync(Order order)
    {
        using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync();
        using var transaction = connection.BeginTransaction();

        try
        {
            // Insert order
            using var orderCmd = new SqlCommand(
                "INSERT INTO Orders (Id, CustomerId, TotalAmount, CreatedDate, Status) " +
                "VALUES (@Id, @CustomerId, @TotalAmount, @CreatedDate, @Status)",
                connection, transaction);
            orderCmd.Parameters.AddWithValue("@Id", order.Id);
            orderCmd.Parameters.AddWithValue("@CustomerId", order.CustomerId);
            orderCmd.Parameters.AddWithValue("@TotalAmount", order.TotalAmount);
            orderCmd.Parameters.AddWithValue("@CreatedDate", order.CreatedDate);
            orderCmd.Parameters.AddWithValue("@Status", (int)order.Status);
            await orderCmd.ExecuteNonQueryAsync();

            // Insert each line item
            foreach (var item in order.LineItems)
            {
                using var itemCmd = new SqlCommand(
                    "INSERT INTO LineItems (Id, OrderId, ProductId, Quantity, UnitPrice) " +
                    "VALUES (@Id, @OrderId, @ProductId, @Quantity, @UnitPrice)",
                    connection, transaction);
                itemCmd.Parameters.AddWithValue("@Id", item.Id);
                itemCmd.Parameters.AddWithValue("@OrderId", order.Id);
                itemCmd.Parameters.AddWithValue("@ProductId", item.ProductId);
                itemCmd.Parameters.AddWithValue("@Quantity", item.Quantity);
                itemCmd.Parameters.AddWithValue("@UnitPrice", item.UnitPrice);
                await itemCmd.ExecuteNonQueryAsync();
            }

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

    // UpdateAsync: another 50 lines
    // DeleteAsync: another 30 lines
    // SearchAsync: another 40 lines
    // Per aggregate root: ~250 lines of ADO.NET boilerplate
}

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
                   namespace="MyApp.Domain" assembly="MyApp.Domain">

  <class name="Order" table="Orders" lazy="true">
    <id name="Id" column="Id" type="Guid">
      <generator class="guid.comb" />
    </id>

    <property name="CustomerId" column="CustomerId" type="Guid" not-null="true" />
    <property name="TotalAmount" column="TotalAmount" type="Decimal" precision="18" scale="2" />
    <property name="CreatedDate" column="CreatedDate" type="DateTime" not-null="true" />
    <property name="Status" column="Status" type="Int32" not-null="true" />

    <bag name="LineItems" cascade="all-delete-orphan" inverse="true" lazy="true">
      <key column="OrderId" />
      <one-to-many class="LineItem" />
    </bag>
  </class>

  <class name="LineItem" table="LineItems" lazy="true">
    <id name="Id" column="Id" type="Guid">
      <generator class="guid.comb" />
    </id>

    <property name="OrderId" column="OrderId" type="Guid" not-null="true" />
    <property name="ProductId" column="ProductId" type="Guid" not-null="true" />
    <property name="Quantity" column="Quantity" type="Int32" not-null="true" />
    <property name="UnitPrice" column="UnitPrice" type="Decimal" precision="18" scale="2" />

    <many-to-one name="Order" class="Order" column="OrderId" insert="false" update="false" />
  </class>

</hibernate-mapping>

// NHibernate session configuration
var config = new Configuration()
    .SetProperty(NHibernate.Cfg.Environment.ConnectionString, connectionString)
    .SetProperty(NHibernate.Cfg.Environment.Dialect, "NHibernate.Dialect.MsSql2012Dialect")
    .AddFile("Mappings/Order.hbm.xml")
    .AddFile("Mappings/LineItem.hbm.xml")
    .AddFile("Mappings/Customer.hbm.xml")
    .AddFile("Mappings/Product.hbm.xml");
    // ... one line per entity. Miss one? Silent mapping failure.

var sessionFactory = config.BuildSessionFactory();

public class AppDbContext : DbContext
{
    public DbSet<Order> Orders { get; set; } = null!;
    public DbSet<LineItem> LineItems { get; set; } = null!;
    public DbSet<Customer> Customers { get; set; } = null!;
    public DbSet<Product> Products { get; set; } = null!;

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Convention: Order maps to "Orders" table (pluralized DbSet name)
        // Convention: Properties map to columns by name
        // Convention: Navigation properties discovered automatically
        // Convention: Required relationships cascade delete

        // But some things need explicit configuration:
        modelBuilder.Entity<Order>(e =>
        {
            e.Property(o => o.TotalAmount).HasPrecision(18, 2);
            e.HasMany(o => o.LineItems)
                .WithOne()
                .HasForeignKey(li => li.OrderId)
                .OnDelete(DeleteBehavior.Cascade);
            e.Navigation(o => o.LineItems).AutoInclude();
        });
    }
}

<!-- wiki/ef-core-conventions.md — the document every team writes -->

# EF Core Conventions and Standards

## Table Naming
- Tables are named after the `DbSet<T>` property (pluralized)
- Exception: join tables for many-to-many use `{Entity1}{Entity2}` format
- Override with `[Table("custom_name")]` only when matching legacy schemas

## Column Naming
- Columns match property names exactly (PascalCase)
- Exception: database uses snake_case → configure in OnModelCreating
- Foreign key columns: `{NavigationProperty}Id` (e.g., `CustomerId`)

## Strongly-Typed IDs
- All entities use strongly-typed IDs (e.g., `OrderId` not `Guid`)
- Value converters registered globally in OnModelCreating:
  ```csharp
  modelBuilder.Entity<Order>().Property(o => o.Id)
      .HasConversion(id => id.Value, v => new OrderId(v));

That's **65 lines** of documentation. And it's already partially outdated because last sprint the team decided to use `snake_case` for a new microservice, and nobody updated the wiki.

### The Enforcement Code

```csharp
// tests/ArchitectureTests/EfConventionTests.cs

public class EfConventionTests
{
    private readonly Assembly _domainAssembly = typeof(Order).Assembly;
    private readonly Assembly _infrastructureAssembly = typeof(AppDbContext).Assembly;

    [Fact]
    public void Aggregate_Roots_Must_Have_StronglyTyped_Ids()
    {
        var aggregateRoots = _domainAssembly.GetTypes()
            .Where(t => !t.IsAbstract && t.BaseType?.Name == "Entity`1");

        foreach (var root in aggregateRoots)
        {
            var idType = root.BaseType!.GetGenericArguments()[0];
            idType.Should().NotBe(typeof(Guid),
                $"Aggregate root {root.Name} must use a strongly-typed ID, not Guid");
            idType.Should().NotBe(typeof(int),
                $"Aggregate root {root.Name} must use a strongly-typed ID, not int");
        }
    }

    [Fact]
    public void Aggregate_Roots_Must_Not_Have_Public_Setters()
    {
        var aggregateRoots = _domainAssembly.GetTypes()
            .Where(t => !t.IsAbstract && t.BaseType?.Name == "Entity`1");

        foreach (var root in aggregateRoots)
        {
            var publicSetters = root.GetProperties(BindingFlags.Public | BindingFlags.Instance)
                .Where(p => p.SetMethod?.IsPublic == true
                    && p.Name != "Id"
                    && !p.SetMethod.ReturnParameter.GetRequiredCustomModifiers()
                        .Contains(typeof(System.Runtime.CompilerServices.IsExternalInit)));

            publicSetters.Should().BeEmpty(
                $"Aggregate root {root.Name} must not have public setters " +
                $"(found: {string.Join(", ", publicSetters.Select(p => p.Name))})");
        }
    }

    [Fact]
    public void Aggregate_Roots_Must_Not_Reference_Other_Aggregates_By_Navigation()
    {
        var aggregateRootTypes = _domainAssembly.GetTypes()
            .Where(t => !t.IsAbstract && t.BaseType?.Name == "Entity`1")
            .ToList();

        foreach (var root in aggregateRootTypes)
        {
            var navigationProperties = root.GetProperties()
                .Where(p => aggregateRootTypes.Contains(p.PropertyType)
                    && p.PropertyType != root);

            navigationProperties.Should().BeEmpty(
                $"Aggregate root {root.Name} references aggregate root " +
                $"{string.Join(", ", navigationProperties.Select(p => p.PropertyType.Name))} " +
                $"by navigation. Use ID reference instead.");
        }
    }

    [Fact]
    public void Collections_Must_Be_IReadOnlyCollection()
    {
        var aggregateRoots = _domainAssembly.GetTypes()
            .Where(t => !t.IsAbstract && t.BaseType?.Name == "Entity`1");

        foreach (var root in aggregateRoots)
        {
            var collectionProperties = root.GetProperties()
                .Where(p => p.PropertyType.IsGenericType
                    && typeof(IEnumerable<>).IsAssignableFrom(
                        p.PropertyType.GetGenericTypeDefinition())
                    && p.PropertyType != typeof(string));

            foreach (var prop in collectionProperties)
            {
                var genericDef = prop.PropertyType.GetGenericTypeDefinition();
                genericDef.Should().Be(typeof(IReadOnlyCollection<>),
                    $"{root.Name}.{prop.Name} must be IReadOnlyCollection<T>, " +
                    $"not {prop.PropertyType.Name}");
            }
        }
    }

    [Fact]
    public void Every_Aggregate_Root_Must_Have_Repository_Interface()
    {
        var aggregateRoots = _domainAssembly.GetTypes()
            .Where(t => !t.IsAbstract && t.BaseType?.Name == "Entity`1");

        var repoInterfaces = _domainAssembly.GetTypes()
            .Where(t => t.IsInterface && t.Name.EndsWith("Repository"))
            .Select(t => t.Name)
            .ToList();

        foreach (var root in aggregateRoots)
        {
            var expectedRepo = $"I{root.Name}Repository";
            repoInterfaces.Should().Contain(expectedRepo,
                $"Aggregate root {root.Name} must have a repository interface {expectedRepo}");
        }
    }

    [Fact]
    public void Every_Repository_Interface_Must_Have_Implementation()
    {
        var repoInterfaces = _domainAssembly.GetTypes()
            .Where(t => t.IsInterface && t.Name.EndsWith("Repository"));

        var repoImplementations = _infrastructureAssembly.GetTypes()
            .Where(t => !t.IsAbstract && !t.IsInterface)
            .SelectMany(t => t.GetInterfaces(), (t, i) => new { Type = t, Interface = i })
            .ToList();

        foreach (var repoInterface in repoInterfaces)
        {
            repoImplementations.Should().Contain(
                x => x.Interface == repoInterface,
                $"Repository interface {repoInterface.Name} must have an implementation " +
                $"in {_infrastructureAssembly.GetName().Name}");
        }
    }

    [Fact]
    public void Value_Objects_Must_Have_Owned_Attribute()
    {
        var valueObjects = _domainAssembly.GetTypes()
            .Where(t => t.IsSubclassOf(typeof(ValueObject)));

        foreach (var vo in valueObjects)
        {
            vo.GetCustomAttributes(typeof(OwnedAttribute), false)
                .Should().NotBeEmpty(
                    $"Value object {vo.Name} must have [Owned] attribute for EF Core mapping");
        }
    }

    [Fact]
    public void DbContext_Should_Only_Have_DbSets_For_Aggregate_Roots()
    {
        var dbSetProperties = typeof(AppDbContext).GetProperties()
            .Where(p => p.PropertyType.IsGenericType
                && p.PropertyType.GetGenericTypeDefinition() == typeof(DbSet<>));

        var aggregateRootTypes = _domainAssembly.GetTypes()
            .Where(t => !t.IsAbstract && t.BaseType?.Name == "Entity`1")
            .ToHashSet();

        foreach (var dbSetProp in dbSetProperties)
        {
            var entityType = dbSetProp.PropertyType.GetGenericArguments()[0];
            aggregateRootTypes.Should().Contain(entityType,
                $"DbSet<{entityType.Name}> exists but {entityType.Name} is not an aggregate root. " +
                $"Only aggregate roots should have DbSet properties.");
        }
    }
}

📄 wiki/ef-core-conventions.md              65 lines    (documentation)
📄 tests/EfConventionTests.cs              130 lines    (enforcement)
📄 DbContext + OnModelCreating               30 lines    (actual config)
📄 Repository implementations (per root)     40 lines    (actual code)
📄 Repository interface (per root)           10 lines    (actual code)
──────────────────────────────────────────────────────
Total per aggregate root:                  ~275 lines
Of which convention overhead:              ~195 lines   (71% overhead)

using Cmf.Ddd;

[AggregateRoot]
public class Order : Entity<OrderId>
{
    public CustomerId CustomerId { get; private set; }

    [Money(precision: 18, scale: 2)]
    public decimal TotalAmount { get; private set; }

    public OrderStatus Status { get; private set; }

    public DateTime CreatedDate { get; private set; }

    private readonly List<LineItem> _lineItems = new();

    [HasMany(cascade: CascadeType.AllDeleteOrphan, autoInclude: true)]
    public IReadOnlyCollection<LineItem> LineItems => _lineItems.AsReadOnly();

    private Order() { } // EF constructor

    public Order(OrderId id, CustomerId customerId) : base(id)
    {
        CustomerId = customerId;
        Status = OrderStatus.Draft;
        CreatedDate = DateTime.UtcNow;
    }

    public void AddLineItem(ProductId productId, int quantity, decimal unitPrice)
    {
        var item = new LineItem(LineItemId.New(), Id, productId, quantity, unitPrice);
        _lineItems.Add(item);
        RecalculateTotal();
    }

    public void Submit()
    {
        if (!_lineItems.Any())
            throw new DomainException("Cannot submit an empty order");
        Status = OrderStatus.Submitted;
    }

    private void RecalculateTotal()
    {
        TotalAmount = _lineItems.Sum(li => li.Total);
    }
}

[Entity]
public class LineItem : Entity<LineItemId>
{
    public OrderId OrderId { get; private set; }
    public ProductId ProductId { get; private set; }
    public int Quantity { get; private set; }

    [Money(precision: 18, scale: 2)]
    public decimal UnitPrice { get; private set; }

    public decimal Total => Quantity * UnitPrice;

    private LineItem() { }

    public LineItem(LineItemId id, OrderId orderId, ProductId productId,
        int quantity, decimal unitPrice) : base(id)
    {
        OrderId = orderId;
        ProductId = productId;
        Quantity = quantity;
        UnitPrice = unitPrice;
    }
}

[ValueObject]
public record Money(decimal Amount, string Currency);

[ValueObject]
public record Address(string Street, string City, string PostalCode, string Country);

// ── Generated: OrderEntityConfiguration.g.cs ──
// <auto-generated />
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
internal sealed class OrderEntityConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders");

        // Primary key with strongly-typed ID conversion
        builder.HasKey(e => e.Id);
        builder.Property(e => e.Id)
            .HasConversion(id => id.Value, v => new OrderId(v))
            .ValueGeneratedNever();

        // Properties with strongly-typed ID conversions
        builder.Property(e => e.CustomerId)
            .IsRequired()
            .HasConversion(id => id.Value, v => new CustomerId(v));

        // [Money] attribute → precision/scale configuration
        builder.Property(e => e.TotalAmount)
            .HasPrecision(18, 2);

        builder.Property(e => e.Status)
            .HasConversion<int>();

        builder.Property(e => e.CreatedDate)
            .IsRequired();

        // [HasMany] attribute → relationship configuration
        builder.HasMany(typeof(LineItem), "_lineItems")
            .WithOne()
            .HasForeignKey(nameof(LineItem.OrderId))
            .OnDelete(DeleteBehavior.Cascade);

        // autoInclude: true from [HasMany] attribute
        builder.Navigation("_lineItems").AutoInclude();
    }
}

// ── Generated: LineItemEntityConfiguration.g.cs ──
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
internal sealed class LineItemEntityConfiguration : IEntityTypeConfiguration<LineItem>
{
    public void Configure(EntityTypeBuilder<LineItem> builder)
    {
        builder.ToTable("LineItems");

        builder.HasKey(e => e.Id);
        builder.Property(e => e.Id)
            .HasConversion(id => id.Value, v => new LineItemId(v))
            .ValueGeneratedNever();

        builder.Property(e => e.OrderId)
            .IsRequired()
            .HasConversion(id => id.Value, v => new OrderId(v));

        builder.Property(e => e.ProductId)
            .IsRequired()
            .HasConversion(id => id.Value, v => new ProductId(v));

        builder.Property(e => e.UnitPrice)
            .HasPrecision(18, 2);

        // Computed property — ignore in EF
        builder.Ignore(e => e.Total);
    }
}

// ── Generated: IOrderRepository.g.cs ──
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct = default);
    Task<IReadOnlyList<Order>> GetAllAsync(CancellationToken ct = default);
    Task AddAsync(Order entity, CancellationToken ct = default);
    Task UpdateAsync(Order entity, CancellationToken ct = default);
    Task DeleteAsync(OrderId id, CancellationToken ct = default);
    Task<bool> ExistsAsync(OrderId id, CancellationToken ct = default);
}

// ── Generated: OrderRepository.g.cs ──
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
internal sealed class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public OrderRepository(AppDbContext context) => _context = context;

    public async Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct)
        => await _context.Set<Order>().FirstOrDefaultAsync(e => e.Id == id, ct);

    public async Task<IReadOnlyList<Order>> GetAllAsync(CancellationToken ct)
        => await _context.Set<Order>().ToListAsync(ct);

    public async Task AddAsync(Order entity, CancellationToken ct)
    {
        await _context.Set<Order>().AddAsync(entity, ct);
        await _context.SaveChangesAsync(ct);
    }

    public async Task UpdateAsync(Order entity, CancellationToken ct)
    {
        _context.Set<Order>().Update(entity);
        await _context.SaveChangesAsync(ct);
    }

    public async Task DeleteAsync(OrderId id, CancellationToken ct)
    {
        var entity = await GetByIdAsync(id, ct);
        if (entity is not null)
        {
            _context.Set<Order>().Remove(entity);
            await _context.SaveChangesAsync(ct);
        }
    }

    public async Task<bool> ExistsAsync(OrderId id, CancellationToken ct)
        => await _context.Set<Order>().AnyAsync(e => e.Id == id, ct);
}

// ── Generated: AppDbContext.g.cs (partial) ──
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
public partial class AppDbContext
{
    // DbSet for aggregate roots only (not for child entities)
    public DbSet<Order> Orders { get; set; } = null!;

    partial void OnModelCreatingGenerated(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfiguration(new OrderEntityConfiguration());
        modelBuilder.ApplyConfiguration(new LineItemEntityConfiguration());
    }
}

// ── Generated: DomainServiceRegistration.g.cs (partial) ──
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
public static partial class DomainServiceRegistration
{
    static partial void AddOrderServices(IServiceCollection services)
    {
        services.AddScoped<IOrderRepository, OrderRepository>();
    }
}

// ── Generated: OrderFactory.g.cs ──
[GeneratedCode("Cmf.Ddd.Generators", "1.0.0")]
public static class OrderFactory
{
    public static Order Create(CustomerId customerId)
        => new Order(OrderId.New(), customerId);
}

// DDD001: Public setter on aggregate root
error DDD001: Property 'Order.Status' has a public setter.
  Aggregate roots must encapsulate state. Use 'private set' or 'init'.
  Location: Order.cs(8,12)

// DDD002: Missing DDD attribute
warning DDD002: Class 'Payment' inherits Entity<PaymentId> but has no
  [AggregateRoot] or [Entity] attribute. Add an attribute to enable code generation.
  Location: Payment.cs(3,14)

// DDD003: Cross-aggregate navigation
error DDD003: Property 'Order.Customer' references aggregate root 'Customer'
  by navigation. Aggregate roots must reference each other by ID.
  Use 'CustomerId' (which you already have) instead of 'Customer'.
  Location: Order.cs(15,20)

// DDD004: Mutable collection
error DDD004: Property 'Order.LineItems' returns List<LineItem>.
  Collections on aggregate roots must use IReadOnlyCollection<T>
  with a private backing field. Example:
    private readonly List<LineItem> _lineItems = new();
    [HasMany(...)]
    public IReadOnlyCollection<LineItem> LineItems => _lineItems.AsReadOnly();
  Location: Order.cs(22,5)

// DDD005: DbSet for non-aggregate
error DDD005: DbSet<LineItem> exists in AppDbContext but LineItem is not
  marked [AggregateRoot]. Only aggregate roots should have DbSet properties.
  Child entities are accessed through their parent aggregate.
  Location: AppDbContext.cs(5,12)

// DDD006: Missing value converter
warning DDD006: Property 'Order.CustomerId' uses strongly-typed ID 'CustomerId'
  but no value converter is configured. The [AggregateRoot] source generator
  handles this automatically — this warning indicates the generator may not
  have run. Rebuild the project.
  Location: Order.cs(4,12)