TaskHub.Shared

Persistence

The Persistence layer is TaskHub’s standardized contract with data stores. It enforces a small set of patterns — Repository + Unit of Work, Outbox for cross-service events, EF Core for relational data, Redis for caching — and provides reusable base classes that handle the wiring.

🎯 Design Goals

1. The Repository owns reads. The Unit of Work owns writes. Handlers never call DbContext.SaveChanges() directly — they go through IUnitOfWork.SaveAsync(), which integrates the Outbox automatically.
2. Aggregates are persistence-aware, but ignorant of EF. Domain types implement IAggregate and raise IDomainEvents; the persistence layer harvests them at save time.
3. Outbox or it didn’t happen. Domain events that cross service boundaries go through the Outbox table, written in the same transaction as the data change. No “fire and forget.”
4. One DbContext per aggregate root family. Cross-context transactions are an anti-pattern.

📦 Modules

Core & Repository

| Module | Purpose | | :— | :— | | Persistence Abstractions | IRepository, IReadRepository<TId, T>, IWriteRepository<TId, T>, IOwnershipRepository<TItem, TOwner>, IUnitOfWork. | | Generic Repository | Generic patterns and registration for repository implementations. |

Database Providers

| Module | Purpose | | :— | :— | | Entity Framework Core | ContextBase, UnitOfWorkBase, automatic outbox/media wiring, configuration scanning. | | Redis | Connection multiplexer setup, options, integration with IDistributedCache. |

Reliability

| Module | Purpose | | :— | :— | | Outbox Abstractions | OutboxMessage, IOutboxReader, IOutboxWriter, IOutboxMessageFactory. | | Outbox EF Core | EF Core implementation: schema, reader, processing loop. |

Domain-Specific

| Module | Purpose | | :— | :— | | Media | Tracks media file metadata (hashes, owner, content type) alongside business data. |

🧭 The Save Pipeline

   Handler                           UnitOfWork.SaveAsync()
   ────────                          ──────────────────────
                                     │
   aggregate.Foo()    ──► raises ──► │ 1. Scan ChangeTracker for IAggregate
   aggregate.Bar()    ──► raises ──► │ 2. Extract IDomainEvent[] from each
                                     │ 3. Convert to OutboxMessage[]
                                     │ 4. SaveChangesAsync()
                                     │       — business rows + outbox rows
                                     │       — single SQL transaction
                                     │ 5. ClearEvents() on each aggregate
                                     ▼
                                  Committed

A separate background worker reads the outbox and publishes to the message bus (RabbitMQ / Kafka / etc.). Even if the worker dies mid-publish, the message stays in the outbox until processed — at-least-once delivery, with the transactional guarantee that no event is ever lost.

⚙️ Minimal Configuration

"Persistence": {
  "ConnectionString": "Host=db;Database=taskhub;Username=app;Password=…",
  "Outbox": {
    "IsEnabled": true,
    "TableName": "outbox_messages",
    "BatchSize": 100,
    "MaxRetryCount": 5,
    "ProcessingInterval": "00:00:10"
  },
  "Media": {
    "IsEnabled": true,
    "TableName": "media_metadata"
  }
},
"Redis": {
  "Endpoint": "redis:6379",
  "InstanceName": "taskhub_"
}

✅ Best Practices

• Always use IUnitOfWork.SaveAsync(). Bypassing it skips the Outbox.
• Keep aggregates thin on persistence: no DbContext injection, no LINQ — that’s the repository’s job.
• One transaction = one aggregate. Need to touch two? Use a saga / process manager fed by domain events.
• Don’t migrate in code on startup at scale. The FullHostBuilder does run migrations on startup, which is convenient for small fleets — but for >3 replicas, run migrations as a separate Job/init container to avoid the startup race.

🔗 See Also

• EF Core architecture — deep dive on UnitOfWorkBase event harvesting.
• Outbox in EF Core — how the outbox is wired into the save pipeline.
• Domain — AggregateBase and the event collection contract this layer reads.

This site is open source. Improve this page.