From dotnet-claude-kit
Implements Domain-Driven Design tactical patterns for .NET: aggregates, roots, value objects, domain events, services, typed IDs, repositories. For DDD aggregates, events, bounded contexts.
npx claudepluginhub codewithmukesh/dotnet-claude-kit --plugin dotnet-claude-kitThis skill uses the workspace's default tool permissions.
1. **Aggregates define consistency boundaries** — An aggregate is a cluster of entities and value objects treated as a single unit for data changes. All invariants within an aggregate are enforced in a single transaction. Cross-aggregate consistency is eventual.
Modeling business domains. Aggregates, value objects, domain events, rich models, repositories.
Applies DDD tactical patterns using entities, value objects, aggregates, repositories, and domain events to enforce explicit invariants in domain code.
Applies DDD tactical patterns to domain code: enforces aggregate design, value objects over primitives, entity identity rules, and bounded context boundaries for domain modeling.
Share bugs, ideas, or general feedback.
Money, EmailAddress, OrderNumber are not strings — they carry validation, equality, and behavior. Use C# records for immutable value objects.DbContext internally — this is a DDD tactical pattern for aggregate boundaries, not a generic CRUD wrapper.The aggregate root owns all access to its children and enforces invariants:
// Domain/Orders/Order.cs
public sealed class Order : AggregateRoot
{
private readonly List<OrderLine> _lines = [];
private Order() { } // EF Core
public OrderNumber Number { get; private set; } = null!;
public CustomerId CustomerId { get; private set; }
public Money Total { get; private set; } = Money.Zero("USD");
public OrderStatus Status { get; private set; }
public DateTimeOffset PlacedAt { get; private set; }
public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();
public static Order Place(CustomerId customerId, OrderNumber number, DateTimeOffset now)
{
var order = new Order
{
Id = Guid.CreateVersion7(),
CustomerId = customerId,
Number = number,
Status = OrderStatus.Placed,
PlacedAt = now
};
order.RaiseDomainEvent(new OrderPlaced(order.Id, customerId, now));
return order;
}
public Result AddLine(ProductId productId, int quantity, Money unitPrice)
{
if (Status is not OrderStatus.Placed)
return Result.Failure("Cannot modify a confirmed or cancelled order");
if (quantity <= 0)
return Result.Failure("Quantity must be positive");
var existing = _lines.FirstOrDefault(l => l.ProductId == productId);
if (existing is not null)
{
existing.IncreaseQuantity(quantity);
}
else
{
_lines.Add(new OrderLine(productId, quantity, unitPrice));
}
RecalculateTotal();
return Result.Success();
}
public Result Confirm()
{
if (Status is not OrderStatus.Placed)
return Result.Failure("Only placed orders can be confirmed");
if (_lines.Count == 0)
return Result.Failure("Cannot confirm an order with no lines");
Status = OrderStatus.Confirmed;
RaiseDomainEvent(new OrderConfirmed(Id));
return Result.Success();
}
private void RecalculateTotal()
{
Total = _lines.Aggregate(Money.Zero(Total.Currency), (sum, line) => sum + line.Subtotal);
}
}
Use C# records for immutable value objects with structural equality:
// Domain/Common/Money.cs
public sealed record Money
{
public decimal Amount { get; }
public string Currency { get; }
public Money(decimal amount, string currency)
{
ArgumentOutOfRangeException.ThrowIfNegative(amount);
ArgumentException.ThrowIfNullOrWhiteSpace(currency);
Amount = amount;
Currency = currency.ToUpperInvariant();
}
public static Money Zero(string currency) => new(0, currency);
public static Money operator +(Money left, Money right)
{
if (left.Currency != right.Currency)
throw new InvalidOperationException($"Cannot add {left.Currency} and {right.Currency}");
return new Money(left.Amount + right.Amount, left.Currency);
}
}
// Other value objects (EmailAddress, OrderNumber, etc.) follow the same pattern:
// sealed record, constructor validation, no public setters
Prevent mixing up GUIDs from different entities:
// Domain/Common/StronglyTypedId.cs
public readonly record struct CustomerId(Guid Value)
{
public static CustomerId New() => new(Guid.CreateVersion7());
public override string ToString() => Value.ToString();
}
public readonly record struct ProductId(Guid Value)
{
public static ProductId New() => new(Guid.CreateVersion7());
}
public readonly record struct OrderNumber(string Value)
{
public override string ToString() => Value;
}
// Infrastructure/Persistence/Configurations/OrderConfiguration.cs
public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
public void Configure(EntityTypeBuilder<Order> builder)
{
builder.HasKey(o => o.Id);
builder.Property(o => o.CustomerId)
.HasConversion(id => id.Value, value => new CustomerId(value));
builder.Property(o => o.Number)
.HasConversion(n => n.Value, value => new OrderNumber(value))
.HasMaxLength(50);
builder.ComplexProperty(o => o.Total, money =>
{
money.Property(m => m.Amount).HasColumnName("Total").HasPrecision(18, 2);
money.Property(m => m.Currency).HasColumnName("Currency").HasMaxLength(3);
});
builder.HasMany(o => o.Lines).WithOne().HasForeignKey("OrderId");
builder.Navigation(o => o.Lines).AutoInclude();
}
}
Raise events in the aggregate, dispatch in SaveChangesAsync:
// Domain/Common/AggregateRoot.cs
public abstract class AggregateRoot : Entity
{
private readonly List<IDomainEvent> _domainEvents = [];
public IReadOnlyList<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();
protected void RaiseDomainEvent(IDomainEvent domainEvent) => _domainEvents.Add(domainEvent);
public void ClearDomainEvents() => _domainEvents.Clear();
}
public interface IDomainEvent : INotification
{
DateTimeOffset OccurredAt { get; }
}
// Domain/Orders/Events/OrderPlaced.cs
public sealed record OrderPlaced(Guid OrderId, CustomerId CustomerId, DateTimeOffset PlacedAt) : IDomainEvent
{
public DateTimeOffset OccurredAt => PlacedAt;
}
// Infrastructure/Persistence/AppDbContext.cs
public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
{
var aggregates = ChangeTracker.Entries<AggregateRoot>()
.Where(e => e.Entity.DomainEvents.Count > 0)
.Select(e => e.Entity)
.ToList();
var events = aggregates.SelectMany(a => a.DomainEvents).ToList();
var result = await base.SaveChangesAsync(ct);
foreach (var @event in events)
await _publisher.Publish(@event, ct);
foreach (var aggregate in aggregates)
aggregate.ClearDomainEvents();
return result;
}
For logic that does not belong to a single aggregate:
// Domain/Orders/Services/PricingService.cs
// Coordinates logic across aggregates — takes domain interfaces, returns value objects
public sealed class PricingService(IDiscountPolicy discountPolicy)
{
public Money CalculatePrice(ProductId productId, int quantity, Money unitPrice, CustomerId customerId)
{
var subtotal = new Money(unitPrice.Amount * quantity, unitPrice.Currency);
var discount = discountPolicy.GetDiscount(customerId, productId, quantity);
return new Money(subtotal.Amount * (1 - discount), subtotal.Currency);
}
}
// BAD — Customer aggregate owns everything the customer touches
public class Customer : AggregateRoot
{
public List<Order> Orders { get; } = []; // should be separate aggregate
public List<Payment> Payments { get; } = []; // should be separate aggregate
public List<Address> Addresses { get; } = []; // might be OK as child
public ShoppingCart Cart { get; set; } // should be separate aggregate
}
// GOOD — small, focused aggregates linked by ID
public class Customer : AggregateRoot
{
public CustomerName Name { get; private set; }
public EmailAddress Email { get; private set; }
// Orders, Payments, Cart are separate aggregates referencing CustomerId
}
// BAD — using events for logic within the same aggregate
order.RaiseDomainEvent(new OrderLineAdded(line));
// Then a handler recalculates the total... but you're in the same aggregate!
// GOOD — just call the method directly within the aggregate
_lines.Add(line);
RecalculateTotal(); // private method, no event needed
// BAD — value object with an Id (it's an entity then!)
public record Address
{
public Guid Id { get; init; } // value objects don't have identity
public string Street { get; init; }
}
// GOOD — value objects are defined by their attributes, not an Id
public record Address(string Street, string City, string PostalCode, string Country);
// BAD — aggregate is just a data bag, service does all the work
public class Order : AggregateRoot
{
public OrderStatus Status { get; set; } // public setter!
public List<OrderLine> Lines { get; set; } = [];
}
// Service directly manipulates order state
order.Status = OrderStatus.Confirmed; // no invariant check!
order.Lines.Add(newLine); // no validation!
// GOOD — aggregate encapsulates rules (see Aggregate Root pattern above)
order.Confirm(); // validates status, raises event
order.AddLine(productId, quantity, unitPrice); // validates, recalculates
| Scenario | Recommendation |
|---|---|
| When to use DDD | Complex domain with business rules that go beyond CRUD |
| When to use value objects | Any concept with validation rules or equality based on attributes, not identity |
| Aggregate size | Keep small — typically 1 root entity + 0-3 child entities. Load the whole aggregate every time |
| Domain events vs integration events | Domain events: within bounded context, same transaction. Integration events: cross-context, via message bus |
| Strongly-typed IDs | Always for aggregate root IDs that cross boundaries. Optional for child entity IDs |
| When NOT to use DDD | Simple CRUD, settings, audit logs, read models — use plain entities |
| Repository vs DbContext | Repository per aggregate root for complex aggregates; IAppDbContext for simpler queries |
| Domain services | Only when logic requires multiple aggregates or external data the aggregate should not know about |