Interface ITransactionalOutboxWriter
Extends outbox staging with external transaction participation for atomic consistency.
public interface ITransactionalOutboxWriter
- Extension Methods
Remarks
Implement this interface when the outbox store must participate in an externally owned database transaction. This is required for event sourcing scenarios where the event append and outbox write must be atomic -- without it, a crash between the two writes causes either lost messages or phantom messages.
Only relational providers that support IDbTransaction (SQL Server, PostgreSQL) should implement this interface. NoSQL providers (CosmosDB, DynamoDB, Firestore, Redis, MongoDB, Elasticsearch) should NOT implement it.
Usage (store-owned unit of work — the canonical event-sourcing flow):
The transactional event store owns the connection and transaction end to end. Inside
ITransactionalEventStore.AppendWithOutboxStagingAsync it opens one transaction,
appends the events, then invokes a stageOutbox callback that calls
StageMessageAsync(OutboundMessage, IDbTransaction, CancellationToken) on that same store-owned transaction, and finally
commits (or rolls back on any failure). The caller never begins or commits the transaction.
// The store invokes this callback on its own transaction, between append and commit:
await transactionalWriter.StageMessageAsync(outboxMessage, transaction, cancellationToken);
Interface hierarchy:
- IOutboxStore -- Core polling-based outbox (stage, get unsent, mark sent/failed)
- IOutboxStoreAdmin -- Admin operations (failed retrieval, scheduled messages, cleanup, stats)
- IOutboxStoreBatch -- Batch mark sent/failed operations
- IMultiTransportOutboxStore -- Per-transport delivery tracking for fan-out scenarios
- ITransactionalOutboxWriter -- External transaction participation for atomic staging (this interface)
Methods
StageMessageAsync(OutboundMessage, IDbTransaction, CancellationToken)
Stages a message within an externally owned database transaction.
ValueTask StageMessageAsync(OutboundMessage message, IDbTransaction transaction, CancellationToken cancellationToken)
Parameters
messageOutboundMessageThe outbound message to stage. Must not be null.
transactionIDbTransactionThe database transaction to enlist the staging write on. Must not be null. The transaction owner (the transactional event store, in the canonical flow) controls its lifecycle (begin, commit, rollback); this method only stages the message on the supplied transaction.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask
A task representing the asynchronous staging operation.
Exceptions
- ArgumentNullException
Thrown when
messageortransactionis null.