Table of Contents

Class OutboundMessage

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

Represents an outbound message staged in the outbox for reliable delivery.

public sealed class OutboundMessage
Inheritance
OutboundMessage
Inherited Members
Extension Methods

Remarks

Outbound messages are created during business operations and staged in the outbox within the same transaction. This ensures that messages are only published if the business operation succeeds, maintaining consistency between state changes and published events.

Constructors

OutboundMessage()

Initializes a new instance of the OutboundMessage class.

public OutboundMessage()

OutboundMessage(string, byte[], string, IDictionary<string, object>?)

Initializes a new instance of the OutboundMessage class with specified values.

public OutboundMessage(string messageType, byte[] payload, string destination, IDictionary<string, object>? headers = null)

Parameters

messageType string

A type name for the message that the message type registry can resolve — its simple name, its assembly-qualified name, or "Namespace.TypeName, AssemblyName".

payload byte[]

The serialized message payload.

destination string

The destination where the message should be delivered.

headers IDictionary<string, object>

Optional message headers and metadata.

Properties

CausationId

Gets or sets the causation identifier linking to the triggering message.

public string? CausationId { get; set; }

Property Value

string

ID of the message that caused this message to be created.

CorrelationId

Gets or sets the correlation identifier for tracing.

public string? CorrelationId { get; set; }

Property Value

string

Correlation ID for distributed tracing and message flow tracking.

CreatedAt

Gets or sets the timestamp when the message was created.

public DateTimeOffset CreatedAt { get; set; }

Property Value

DateTimeOffset

UTC timestamp of message creation.

Destination

Gets or sets the destination where the message should be delivered.

public string Destination { get; set; }

Property Value

string

Queue name, topic, endpoint, or routing key for message delivery.

DispatcherId

Gets or sets the identifier of the claim under which this message was handed to the caller.

public string? DispatcherId { get; set; }

Property Value

string

The claim stamp recorded on the row when this message was claimed, or null when the message was not obtained through a claim.

Remarks

This identifies the CLAIM, not the process. Two claims made by the same processor -- a message whose lease lapsed while a dispatch hung, then re-claimed by the next drain cycle -- carry different values, which is the whole point: a completion reported against a claim that has since been superseded must be distinguishable from one reported by the current holder, and a per-process identity cannot tell them apart.

Callers pass it back on the completion members so the store can decline a write from a caller that no longer holds the claim. It travels ON the claimed message deliberately: a lookup keyed by message id would be overwritten by the re-claim, and the stale caller would then read the winner's stamp and pass the very guard it is meant to fail.

GroupKey

Gets or sets the group key for logical message grouping.

public string? GroupKey { get; set; }

Property Value

string

The group key string, or null for no grouping.

Remarks

Used for message deduplication and logical grouping across partitions. Maps to Kafka message key, Azure Service Bus message group, or SQS deduplication ID prefix. When null, no grouping is applied.

Headers

Gets the message headers and metadata.

public IDictionary<string, object> Headers { get; init; }

Property Value

IDictionary<string, object>

Dictionary containing routing information, correlation IDs, and other message properties.

Id

Gets or sets the unique identifier of the outbound message.

public string Id { get; set; }

Property Value

string

A unique message identifier, typically a GUID.

IsMultiTransport

Gets or sets whether this message requires delivery to multiple transports.

public bool IsMultiTransport { get; set; }

Property Value

bool

True if multi-transport delivery is enabled.

LastAttemptAt

Gets or sets the timestamp of the last delivery attempt.

public DateTimeOffset? LastAttemptAt { get; set; }

Property Value

DateTimeOffset?

UTC timestamp of the most recent delivery attempt.

LastError

Gets or sets the error message if delivery failed.

public string? LastError { get; set; }

Property Value

string

Error description or exception message, null if no error occurred.

MessageType

Gets or sets the name under which the message's .NET type is registered.

public string MessageType { get; set; }

Property Value

string

A type name the message type registry can resolve, used to reconstruct the message when the entry is dispatched. The framework's own writers are not uniform — outbox staging from the dispatch pipeline stores the simple name (Type.Name), while direct publication through the message-bus publisher stores Type.FullName. Both resolve. An ambiguous simple name — one shared by two registered types — resolves to nothing rather than to either of them, so a collision fails loudly at resolution rather than deserializing the payload as the wrong type.

PartitionKey

Gets or sets the partition key for ordered delivery within the same partition.

public string? PartitionKey { get; set; }

Property Value

string

The partition key string, or null for default partitioning.

Remarks

Messages with the same partition key are guaranteed to be delivered in order. Maps to Kafka partition key, Azure Service Bus session ID, or SQS message group ID. When null, the transport uses its default partitioning strategy.

Payload

Gets or sets the serialized message payload.

public byte[] Payload { get; set; }

Property Value

byte[]

The message data as bytes, typically JSON or binary format.

Priority

Gets or sets the message priority for delivery ordering.

public int Priority { get; set; }

Property Value

int

Priority level, with higher values indicating higher priority.

RetryCount

Gets or sets the number of delivery attempts made.

public int RetryCount { get; set; }

Property Value

int

The retry count, starting from 0 for the first attempt.

ScheduledAt

Gets or sets the timestamp when the message should be delivered.

public DateTimeOffset? ScheduledAt { get; set; }

Property Value

DateTimeOffset?

UTC timestamp for scheduled delivery, null for immediate delivery.

SentAt

Gets or sets the timestamp when the message was successfully sent.

public DateTimeOffset? SentAt { get; set; }

Property Value

DateTimeOffset?

UTC timestamp of successful delivery, null if not yet sent.

SequenceNumber

Gets or sets the monotonically increasing sequence number for ordering guarantees.

public long SequenceNumber { get; set; }

Property Value

long

A monotonically increasing sequence value, or 0 for unsequenced messages.

Remarks

When PartitionKey is set, messages with the same partition key MUST be delivered in ascending SequenceNumber order. Outbox processors use this value to restore ordering after batch failures and retries.

The value is typically assigned by the outbox store during staging. A value of 0 means no explicit sequencing was requested -- ordering falls back to CreatedAt.

Status

Gets or sets the current delivery status of the message.

public OutboxStatus Status { get; set; }

Property Value

OutboxStatus

The outbox status indicating the delivery state.

TargetTransports

Gets or sets the list of target transports for this message.

public string? TargetTransports { get; set; }

Property Value

string

A comma-separated list of transport names, or null for default routing.

TenantId

Gets or sets the tenant identifier this message belongs to.

public string? TenantId { get; set; }

Property Value

string

The tenant identifier. Settable as null when staging a message that carries no tenant; on the way back out of a store it is never null — see the remarks.

Remarks

Staging accepts an absence; the drain never returns one. A message staged with null here is drained carrying UntenantedSentinel — the reserved untenanted partition — on every conformant store. Untenanted is a value, not an absence: a second spelling of "no tenant" is a fold, and every fold is a place two paths can disagree about which partition a message belongs to.

So a handler must not branch on TenantId is null to mean untenanted. Compare against UntenantedSentinel, or route the value through FromStoredValue(string?), which is total over every spelling.

This postcondition is a contract on the store, enforced by the published outbox conformance kit rather than by this type — the property is settable so that staging can express "no tenant", which means the type itself cannot make the absence unrepresentable.

TransportDeliveries

Gets the per-transport delivery records.

public ICollection<OutboundMessageTransport> TransportDeliveries { get; }

Property Value

ICollection<OutboundMessageTransport>

Remarks

Tracks the delivery status of the message to each target transport independently, for multi-transport fan-out.

Per-transport delivery state is persisted in a separate per-transport delivery table, not as a column on the single-message outbox row — so it is intentionally not a field on the message read/query projection. The single-message read path leaves this collection empty; the publisher then loads the per-transport deliveries on demand by message id when it needs them. Adding a delivered transport to this collection is what marks the message multi-transport (see AddTransport(string, string?)).

Methods

AddTransport(string, string?)

Adds a target transport for delivery.

public OutboundMessageTransport AddTransport(string transportName, string? destination = null)

Parameters

transportName string

The transport name.

destination string

Optional transport-specific destination.

Returns

OutboundMessageTransport

The created transport delivery record.

AreAllTransportsComplete()

Determines if all transport deliveries are complete.

public bool AreAllTransportsComplete()

Returns

bool

True if all transports have been sent or skipped.

FromContext(string, byte[], string, IMessageContext, IDictionary<string, object>?)

Creates an OutboundMessage from a dispatch message and its processing context, propagating the cross-cutting context fields (correlation, causation, and tenant) onto the staged message in a single place.

public static OutboundMessage FromContext(string messageType, byte[] payload, string destination, IMessageContext context, IDictionary<string, object>? headers = null)

Parameters

messageType string

A type name for the message that the message type registry can resolve — its simple name, its assembly-qualified name, or "Namespace.TypeName, AssemblyName".

payload byte[]

The serialized message payload.

destination string

The destination where the message should be delivered.

context IMessageContext

The message context the cross-cutting fields are copied from.

headers IDictionary<string, object>

Optional message headers and metadata.

Returns

OutboundMessage

A staged OutboundMessage with context fields applied.

Remarks

This is the single canonical mapping from IMessageContext to a staged OutboundMessage. Every direct IOutboxStore.EnqueueAsync implementation MUST create its message through this factory so that tenant scope (and correlation/causation) cannot be silently dropped on a convenience path — making the cross-tenant misdelivery bug structurally inexpressible rather than relying on each store to remember to copy the field.

Exceptions

ArgumentNullException

Thrown when context is null.

GetAge()

Gets the age of the message since creation.

public TimeSpan GetAge()

Returns

TimeSpan

The time elapsed since the message was created.

GetFailedTransportDeliveries()

Gets all failed transport deliveries.

public IEnumerable<OutboundMessageTransport> GetFailedTransportDeliveries()

Returns

IEnumerable<OutboundMessageTransport>

Transport deliveries that have failed.

GetPendingTransportDeliveries()

Gets all pending transport deliveries.

public IEnumerable<OutboundMessageTransport> GetPendingTransportDeliveries()

Returns

IEnumerable<OutboundMessageTransport>

Transport deliveries that are pending.

GetTimeSinceLastAttempt()

Gets the age of the message since last delivery attempt.

public TimeSpan? GetTimeSinceLastAttempt()

Returns

TimeSpan?

The time elapsed since the last delivery attempt, null if never attempted.

GetTransportDelivery(string)

Gets the delivery record for a specific transport.

public OutboundMessageTransport? GetTransportDelivery(string transportName)

Parameters

transportName string

The transport name.

Returns

OutboundMessageTransport

The transport delivery record, or null if not found.

IsEligibleForRetry(int, int, bool, int)

Determines if the message is eligible for retry delivery.

public bool IsEligibleForRetry(int maxRetries = 3, int retryDelayMinutes = 5, bool useExponentialBackoff = false, int maxRetryDelayMinutes = 30)

Parameters

maxRetries int

Maximum number of retry attempts allowed.

retryDelayMinutes int

Minimum delay between retry attempts in minutes.

useExponentialBackoff bool

Whether to use exponential backoff for retry delays.

maxRetryDelayMinutes int

Maximum retry delay in minutes when using exponential backoff.

Returns

bool

True if the message can be retried, false otherwise.

IsReadyForDelivery()

Determines if the message is ready for delivery.

public bool IsReadyForDelivery()

Returns

bool

True if the message can be sent now, false otherwise.

MarkFailed(string)

Marks the message as failed with the specified error.

public void MarkFailed(string error)

Parameters

error string

The error description.

MarkSending()

Marks the message as currently being sent.

public void MarkSending()

MarkSent()

Marks the message as successfully sent.

public void MarkSent()

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

UpdateAggregateStatus()

Updates the aggregate status based on transport delivery statuses.

public void UpdateAggregateStatus()