Aggregate Persistence, Owned/Complex Types, Value Objects, Domain Events, and Transactional Outbox Design

Learning outcomes

1. Aggregate persistence is about consistency boundaries, not object graphs

In domain-driven design (DDD), an aggregate is a cluster of domain objects changed through one consistency boundary. ServiceHub’s WorkOrder already has encapsulated operations, Revision concurrency, notes/tags, ServiceAddress, tenant state and soft-delete policy. EF should persist that model without moving invariants into controllers or public setters.

2. Preserve the established complex value object

public sealed record ServiceAddress(    string Line1,    string City,    string Region,    string PostalCode,    string CountryCode);builder.ComplexProperty(x => x.ServiceAddress);

EF Core 10 complex types have no identity and use value semantics, which fits an address owned conceptually by the WorkOrder. Owned entity types remain useful when the dependent needs entity-like navigation/collection mapping, but they carry hidden identity semantics. Do not choose by naming convention; choose by domain semantics and required relational mapping.

3. Domain events are in-memory facts about completed domain decisions

public interface IDomainEvent{    Guid EventId { get; }    DateTimeOffset OccurredUtc { get; }}public sealed record WorkOrderSummaryRevised(    Guid EventId, DateTimeOffset OccurredUtc, int WorkOrderId,    string TenantId, Guid Revision) : IDomainEvent;public sealed partial class WorkOrder{    private readonly List<IDomainEvent> _domainEvents = [];    public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents;    public void ReviseSummary(string summary, TimeProvider clock)    {        SetSummary(summary);        AdvanceRevision();        _domainEvents.Add(new WorkOrderSummaryRevised(            Guid.NewGuid(), clock.GetUtcNow(), Id, TenantId, Revision));    }    public void ClearDomainEvents() => _domainEvents.Clear();}

The event says the aggregate accepted a change; it is not yet proof that a remote subscriber received anything. That requires a durable integration mechanism.

4. Deliberate failure: publish externally during SavingChanges

public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(    DbContextEventData eventData,    InterceptionResult<int> result,    CancellationToken ct = default){    await broker.PublishAsync("WorkOrderChanged", payload, ct);    return result;}

If the broker succeeds and the database transaction later fails, consumers observe a phantom event. If the database commits and the process dies before a later publish, the event is lost. A SaveChanges interceptor cannot make two independent resource managers atomic.

5. Transactional outbox: persist intent beside business state

public sealed class OutboxMessage{    public Guid Id { get; init; }    public DateTime OccurredUtc { get; init; }    public string Type { get; init; } = null!;    public string PayloadJson { get; init; } = null!;    public DateTime? ProcessedUtc { get; set; }}

foreach (var entry in db.ChangeTracker.Entries<WorkOrder>()){    foreach (var evt in entry.Entity.DomainEvents)    {        db.Set<OutboxMessage>().Add(new OutboxMessage        {            Id = evt.EventId,            OccurredUtc = evt.OccurredUtc.UtcDateTime,            Type = evt.GetType().Name,            PayloadJson = JsonSerializer.Serialize(evt, evt.GetType())        });    }}await db.SaveChangesAsync(ct); // work_order UPDATE + outbox INSERT, one DB transactionforeach (var entry in db.ChangeTracker.Entries<WorkOrder>())    entry.Entity.ClearDomainEvents();

Use an interceptor or explicit application service to perform this capture, but test ordering carefully. Clear in-memory events only after a successful commit path; failed SaveChanges must remain retry-safe.

6. Dispatch after commit and assume at-least-once delivery

var pending = await db.Set<OutboxMessage>()    .Where(x => x.ProcessedUtc == null)    .OrderBy(x => x.OccurredUtc)    .Take(100)    .ToListAsync(ct);foreach (var message in pending){    await publisher.PublishAsync(        message.Type, message.PayloadJson,        idempotencyKey: message.Id.ToString(), ct);    message.ProcessedUtc = clock.GetUtcNow().UtcDateTime;    await db.SaveChangesAsync(ct);}

A crash after publish but before ProcessedUtc can cause replay, so consumers need idempotency/deduplication. The outbox solves the local atomicity gap; it does not provide exactly-once network delivery.

7. Evidence: one transaction contains aggregate and outbox commands

Arrange: WorkOrder revision event + outbox captureInject: force a database constraint failure after event creationExpect: SaveChanges throws; neither WorkOrder change nor OutboxMessage existsRetry corrected command: both business change and outbox row commitDispatcher crash after broker publish: same OutboxMessage may be retried -> consumer dedupes by Id

Use a fresh context after failure to verify store state. Do not infer atomicity from the original tracker.

8. Mandatory lab: aggregate → outbox → relay

1. Keep the Chapter 06 ServiceAddress, Chapter 04 Revision and Chapter 22 tenant model.
2. Add one domain event to ReviseSummary.
3. Persist an OutboxMessage in the same SaveChanges transaction.
4. Force a database failure and prove neither change is committed.
5. Run a local fake publisher relay and mark the outbox row processed only after publish.
6. Simulate relay replay and prove idempotency by message ID.

9. Production judgment and bridge

Keep domain invariants in aggregate methods; use complex/owned mappings according to identity semantics; treat domain events as intent; use a transactional outbox for durable integration intent and an independently retryable dispatcher. The next lesson separates write-model requirements from read-model/hot-path tooling without turning CQRS into mandatory distributed infrastructure.

Authoritative references

• EF Core complex types — value-object semantics and EF Core 10 complex mapping
• Owned entity types — owned identity/aggregate-like mapping and comparison with complex types
• EF Core interceptors — SaveChanges interception mechanics and limitations
• Transactions in EF Core — atomic database transaction behavior
• Asynchronous message communication — Microsoft guidance describing outbox as a transactional table for resilient publish intent
• DDD/CQRS microservice guidance — write/read responsibility separation in domain-oriented systems