Class OutboundMessage
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
messageTypestringA type name for the message that the message type registry can resolve — its simple name, its assembly-qualified name, or "Namespace.TypeName, AssemblyName".
payloadbyte[]The serialized message payload.
destinationstringThe destination where the message should be delivered.
headersIDictionary<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 storesType.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
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
transportNamestringThe transport name.
destinationstringOptional 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
messageTypestringA type name for the message that the message type registry can resolve — its simple name, its assembly-qualified name, or "Namespace.TypeName, AssemblyName".
payloadbyte[]The serialized message payload.
destinationstringThe destination where the message should be delivered.
contextIMessageContextThe message context the cross-cutting fields are copied from.
headersIDictionary<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
contextis 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
transportNamestringThe 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
maxRetriesintMaximum number of retry attempts allowed.
retryDelayMinutesintMinimum delay between retry attempts in minutes.
useExponentialBackoffboolWhether to use exponential backoff for retry delays.
maxRetryDelayMinutesintMaximum 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
errorstringThe 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()