Table of Contents

Interface ITransactionalInboxStore

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

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

messageId string

The unique identifier of the message.

handlerType string

The fully qualified type name of the handler processing the message.

handler Func<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.

cancellationToken CancellationToken

Token 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 — handler is 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 messageId or handlerType is null or empty.