Interface IScopedTransactionalInboxStore
An optional capability for IInboxStore implementations backed by a document store whose native transaction cannot be expressed as a BCL IDbTransaction, enabling exactly-once processing: the handler runs and the message is marked processed inside a single provider-native transaction that commits or rolls back atomically.
public interface IScopedTransactionalInboxStore
- Extension Methods
Remarks
This is the document-store analogue of ITransactionalInboxStore. Where the relational seam
hands the handler a BCL IDbTransaction, this seam hands it an opaque
IInboxTransactionScope; a handler that needs to enlist its own writes casts the scope to the
provider-native handle through a provider-specific extension (for example scope.AsMongoSession()).
Presence is reported through SupportsTransactional so a
ValidateOnStart guard can fail fast rather than throw at runtime. A store that cannot honour the
atomic contract (for example a Cosmos DB store configured without a shared partition key, whose
TransactionalBatch is single-partition) MUST report false and fall back to the
at-least-once idempotent claim protocol (IClaimableInboxStore) — a documented,
structurally-guarded degradation, never a false atomic advertisement.
The exactly-once guarantee holds only on the success path: if the handler throws, the whole native transaction rolls back — nothing is marked processed and the message is redelivered for retry.
Methods
TryProcessTransactionallyAsync(string, string, Func<IInboxTransactionScope, CancellationToken, ValueTask>, CancellationToken)
Atomically, within a single provider-native transaction, checks the message has not already been
processed, runs handler, and marks the message processed — committing the handler's
enlisted writes and the processed-mark together, or rolling both back on failure.
ValueTask<bool> TryProcessTransactionallyAsync(string messageId, string handlerType, Func<IInboxTransactionScope, CancellationToken, ValueTask> handler, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message.
handlerTypestringThe fully qualified type name of the handler processing the message.
handlerFunc<IInboxTransactionScope, CancellationToken, ValueTask>The processing delegate, invoked exactly once inside the native transaction if and only if the message was not already processed. It receives an opaque IInboxTransactionScope; writes it performs through the provider-native handle obtained from that scope commit atomically with the processed-mark. Writes made outside the scope 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).
Exceptions
- ArgumentException
Thrown when
messageIdorhandlerTypeis null or empty.