Table of Contents

Class MessageInbox

Namespace
Excalibur.Dispatch.Delivery
Assembly
Excalibur.Outbox.dll

Default implementation of IInbox that coordinates storage, serialization, and processing of inbox messages. Wraps IInboxStore persistence and IInboxProcessor execution to provide a cohesive API for the inbox pattern.

public sealed class MessageInbox : IInbox, IAsyncDisposable
Inheritance
MessageInbox
Implements
Inherited Members

Constructors

MessageInbox(IInboxStore, IInboxProcessor, DispatchJsonSerializer, IPayloadSerializer?, IOptions<InboxOptions>, ILogger<MessageInbox>)

Initializes a new instance of the MessageInbox class with pluggable serialization.

public MessageInbox(IInboxStore inboxStore, IInboxProcessor processor, DispatchJsonSerializer serializer, IPayloadSerializer? payloadSerializer, IOptions<InboxOptions> options, ILogger<MessageInbox> logger)

Parameters

inboxStore IInboxStore

Persistent inbox storage implementation.

processor IInboxProcessor

Processor responsible for executing inbox work items.

serializer DispatchJsonSerializer

Serializer used to persist message payloads (fallback).

payloadSerializer IPayloadSerializer

Optional pluggable serializer for message payloads.

options IOptions<InboxOptions>

Inbox configuration options.

logger ILogger<MessageInbox>

Structured logger for diagnostics.

MessageInbox(IInboxStore, IInboxProcessor, DispatchJsonSerializer, IOptions<InboxOptions>, ILogger<MessageInbox>)

Initializes a new instance of the MessageInbox class.

public MessageInbox(IInboxStore inboxStore, IInboxProcessor processor, DispatchJsonSerializer serializer, IOptions<InboxOptions> options, ILogger<MessageInbox> logger)

Parameters

inboxStore IInboxStore

Persistent inbox storage implementation.

processor IInboxProcessor

Processor responsible for executing inbox work items.

serializer DispatchJsonSerializer

Serializer used to persist message payloads.

options IOptions<InboxOptions>

Inbox configuration options.

logger ILogger<MessageInbox>

Structured logger for diagnostics.

Methods

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

RunInboxDispatchAsync(string, CancellationToken)

Asynchronously processes all pending messages in the inbox for the specified dispatcher, ensuring each is processed effectively once (a redelivered message is skipped, not reprocessed) and proper message ordering where required.

public Task<int> RunInboxDispatchAsync(string dispatcherId, CancellationToken cancellationToken)

Parameters

dispatcherId string

The unique identifier of the dispatcher instance processing messages, used for coordination and preventing concurrent processing conflicts in multi-instance deployments.

cancellationToken CancellationToken

Token to monitor for cancellation requests during inbox processing.

Returns

Task<int>

A task that represents the asynchronous inbox processing operation, containing the number of messages successfully processed during this execution.

Remarks

This method implements the core inbox processing logic, handling message deduplication, ordering constraints, and error recovery. It processes messages in a transactionally safe manner, ensuring that message processing and inbox state updates are atomic. Failed message processing may result in messages being retried according to configured retry policies.

Exceptions

ArgumentException

Thrown when dispatcherId is null, empty, or whitespace.

SaveMessageAsync<TMessage>(TMessage, string, IMessageMetadata, CancellationToken)

Asynchronously saves a message to the inbox with deduplication tracking, ensuring that duplicate messages (identified by external ID) are not processed multiple times.

public Task SaveMessageAsync<TMessage>(TMessage message, string externalId, IMessageMetadata metadata, CancellationToken cancellationToken) where TMessage : IDispatchMessage

Parameters

message TMessage

The message instance to save for future processing.

externalId string

A unique external identifier for the message, typically from the originating system, used for deduplication and idempotency checking.

metadata IMessageMetadata

Message metadata containing correlation information, timestamps, and other contextual data needed for proper message processing and tracing.

cancellationToken CancellationToken

Token to monitor for cancellation requests during save operations.

Returns

Task

A task that represents the asynchronous message save operation.

Type Parameters

TMessage

The type of message to save, must implement IDispatchMessage.

Remarks

This method implements the message storage aspect of the inbox pattern, ensuring that incoming messages are durably persisted with proper deduplication tracking. If a message with the same external ID has already been processed, the implementation may choose to ignore the duplicate or handle it according to configured duplicate message policies. The method should be transactionally safe and handle concurrent message arrival scenarios appropriately.

Exceptions

ArgumentNullException

Thrown when message, externalId, or metadata is null.