Interface ITransactionalInboxStore
An optional capability for IInboxStore implementations backed by a store that supports an enlisting transaction, enabling exactly-once processing: the handler runs and the message is marked processed inside a single transaction that commits or rolls back atomically.
public interface ITransactionalInboxStore
- Extension Methods
Remarks
This is a segregated capability interface (composition, NOT inheritance of IInboxStore) so
IInboxStore stays within the Interface Segregation threshold. Only stores whose backing
engine can enlist the handler's own writes and the processed-mark in one transaction (for example
SqlServer and Postgres) implement it. Stores that cannot fall back to the atomic claim protocol
(IClaimableInboxStore), which is at-least-once (handler and mark are separate
operations, so a crash between them redelivers) — a documented, structurally-guarded degradation, never a
silent one. Presence is reported through SupportsTransactional so a
ValidateOnStart guard can fail fast rather than throw NotSupportedException at
runtime.
The exactly-once guarantee holds only on the success path: if the handler throws, the whole transaction rolls back — nothing is marked processed and the message is redelivered for retry, so a handler failure never silently drops a message and never marks a message whose handler did not commit.
Methods
TryProcessTransactionallyAsync(string, string, Func<IDbTransaction, CancellationToken, ValueTask>, CancellationToken)
Atomically, within a single enlisting transaction, checks the message has not already been processed,
runs handler, and marks the message processed — committing the handler's writes and
the processed-mark together, or rolling both back on failure.
ValueTask<bool> TryProcessTransactionallyAsync(string messageId, string handlerType, Func<IDbTransaction, CancellationToken, ValueTask> handler, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message.
handlerTypestringThe fully qualified type name of the handler processing the message.
handlerFunc<IDbTransaction, CancellationToken, ValueTask>The processing delegate, invoked exactly once inside the transaction if and only if the message was not already processed. It receives the store's active IDbTransaction: any data writes it performs on Connection enlisted in that transaction (for example, Dapper commands passing
transaction: tx) commit atomically with the processed-mark. Writes made on a different connection are not enlisted and are therefore not atomic with the mark.cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask<bool>
true if the caller processed the message (handler ran and the processed-mark committed); false if the message was already processed (a duplicate —
handleris not invoked).
Remarks
The atomic mark+handler commit uses a single local database transaction (one connection) — never an
ambient/distributed transaction (no TransactionScope/MSDTC), so it is portable across hosts and does
not require a distributed transaction coordinator. The seam takes the BCL IDbTransaction so
the messaging-layer abstraction stays free of any data-access-layer dependency.
Exceptions
- ArgumentException
Thrown when
messageIdorhandlerTypeis null or empty.