Table of Contents

Interface ITransactionalOutboxWriter

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

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:

Methods

StageMessageAsync(OutboundMessage, IDbTransaction, CancellationToken)

Stages a message within an externally owned database transaction.

ValueTask StageMessageAsync(OutboundMessage message, IDbTransaction transaction, CancellationToken cancellationToken)

Parameters

message OutboundMessage

The outbound message to stage. Must not be null.

transaction IDbTransaction

The 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.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask

A task representing the asynchronous staging operation.

Exceptions

ArgumentNullException

Thrown when message or transaction is null.