ddd

Domain-Driven Design Patterns

Reference material for applying DDD tactical patterns in .NET. Used by dnp-architect and dnp-planner.

When to Use DDD

Use DDD when: 3+ aggregates with complex business rules, cross-aggregate invariants that need enforcement, or event sourcing is being considered. For simpler CRUD-heavy APIs, Vertical Slice Architecture is lower ceremony. See knowledge/decisions/adr-005-multi-architecture.md.

Aggregate Root Base

All changes to an aggregate go through the root — never modify child entities directly from outside.

// Domain/Common/AggregateRoot.cs
public abstract class AggregateRoot<TId>
{
    private readonly List<IDomainEvent> _events = [];
    public TId Id { get; protected set; } = default!;
    public IReadOnlyList<IDomainEvent> DomainEvents => _events.AsReadOnly();
    protected void Raise(IDomainEvent @event) => _events.Add(@event);
    public void ClearEvents() => _events.Clear();
}

Aggregate Example

// Domain/Orders/Order.cs
public sealed class Order : AggregateRoot<OrderId>
{
    private readonly List<OrderItem> _items = [];
    public IReadOnlyList<OrderItem> Items => _items.AsReadOnly();
    public CustomerId CustomerId { get; private set; } = null!;
    public OrderStatus Status { get; private set; }
    public Money Total { get; private set; } = Money.Zero;

    private Order() { } // required by EF Core

    public static Order Create(CustomerId customerId, IReadOnlyList<CreateOrderItemData> items)
    {
        ArgumentNullException.ThrowIfNull(customerId);
        if (items.Count == 0) throw new DomainException("Order must have at least one item.");

        var order = new Order
        {
            Id = OrderId.New(),
            CustomerId = customerId,
            Status = OrderStatus.Pending
        };

        foreach (var item in items)
            order._items.Add(OrderItem.Create(item));

        order.Total = order._items.Aggregate(Money.Zero, (sum, i) => sum + i.LineTotal);
        order.Raise(new OrderCreatedEvent(order.Id, customerId));
        return order;
    }

    public Result<Unit, OrderError> Cancel()
    {
        if (Status == OrderStatus.Shipped)
            return OrderError.CannotCancelShippedOrder;

        Status = OrderStatus.Cancelled;
        Raise(new OrderCancelledEvent(Id));
        return Result.Success(Unit.Value);
    }

    public Result<Unit, OrderError> AddItem(OrderItem item)
    {
        if (Status != OrderStatus.Pending)
            return OrderError.CannotModifyNonPendingOrder;

        _items.Add(item);
        Total = Total + item.LineTotal;
        return Result.Success(Unit.Value);
    }
}