Table of Contents

Class MessageEnvelope

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

Unified message envelope that consolidates all message context implementations into a single, extensible type.

public sealed class MessageEnvelope : IMessageContext, IDisposable
Inheritance
MessageEnvelope
Implements
Inherited Members
Extension Methods

Remarks

This envelope replaces the 20+ separate context implementations with a single unified type that supports:

  • Core message properties (ID, correlation, causation, timestamps)
  • Extensible headers dictionary for custom metadata
  • Extensible properties bag for runtime state
  • Provider-specific metadata support
  • Pooling and reset capabilities for high-performance scenarios
  • Proper serialization attributes for JSON and other formats

Constructors

MessageEnvelope()

Initializes a new instance of the MessageEnvelope class.

public MessageEnvelope()

MessageEnvelope(IDispatchMessage)

Initializes a new instance of the MessageEnvelope class with a message.

public MessageEnvelope(IDispatchMessage message)

Parameters

message IDispatchMessage

The message to encapsulate.

Properties

AcknowledgeAsync

Gets or sets an optional acknowledgment callback for channel-based processing.

[JsonIgnore]
public Func<CancellationToken, Task>? AcknowledgeAsync { get; set; }

Property Value

Func<CancellationToken, Task>

Remarks

Acknowledgment is transport I/O (e.g. SQS DeleteMessage, RabbitMQ BasicAck) and therefore honors cancellation via the supplied CancellationToken.

AuthorizationResult

Gets or sets the authorization result for the message.

[JsonIgnore]
public IAuthorizationResult AuthorizationResult { get; set; }

Property Value

IAuthorizationResult

Body

Gets or sets the message body for legacy compatibility.

[JsonPropertyName("body")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? Body { get; set; }

Property Value

string

CausationId

Gets or sets the causation identifier linking this message to its cause.

[JsonPropertyName("causationId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? CausationId { get; set; }

Property Value

string

The causation identifier or null.

ContentType

Gets or sets the content type.

[JsonPropertyName("contentType")]
public string? ContentType { get; set; }

Property Value

string

ContractVersion

Gets or sets the contract version.

[JsonPropertyName("contractVersion")]
public string? ContractVersion { get; set; }

Property Value

string

CorrelationId

Gets or sets the correlation identifier for tracking related messages.

[JsonPropertyName("correlationId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? CorrelationId { get; set; }

Property Value

string

The correlation identifier or null.

DeadLetterErrorDescription

Gets or sets the dead letter error description.

[JsonPropertyName("deadLetterErrorDescription")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? DeadLetterErrorDescription { get; set; }

Property Value

string

DeadLetterReason

Gets or sets the dead letter reason.

[JsonPropertyName("deadLetterReason")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? DeadLetterReason { get; set; }

Property Value

string

DeliveryCount

Gets or sets the delivery count.

[JsonPropertyName("deliveryCount")]
public int DeliveryCount { get; set; }

Property Value

int

DesiredVersion

Gets or sets the desired message version.

[JsonPropertyName("desiredVersion")]
public int? DesiredVersion { get; set; }

Property Value

int?

ExternalId

Gets or sets the external identifier.

[JsonPropertyName("externalId")]
public string? ExternalId { get; set; }

Property Value

string

Features

Gets the typed feature collection for accessing cross-cutting concerns.

[JsonIgnore]
public IDictionary<Type, object> Features { get; }

Property Value

IDictionary<Type, object>

The features dictionary keyed by feature interface type.

Remarks

Features provide typed access to processing state, identity, routing, validation, timeout, rate limiting, and transaction contexts. Use extension methods from MessageContextFeatureExtensions for convenient access:

var processing = context.GetOrCreateProcessingFeature();
processing.ProcessingAttempts++;

Contract an implementation must keep — the same one Items states, and now load-bearing here too. Returns the one collection owned by this context. Never null. The same instance on every call, for the life of the context. Mutable, and a write is observable to every subsequent read. Returning a fresh collection per call satisfies the signature and breaks this framework silently: the propagated set (SetPropagatedItem(IMessageContext, string, string)) is stored here, so a context that forgets a feature write loses every marked value with nothing raised and nothing logged.

Headers

Gets the extensible headers dictionary for custom metadata.

[JsonPropertyName("headers")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public IDictionary<string, string> Headers { get; }

Property Value

IDictionary<string, string>

Items

Gets this context's request-local scratch collection.

[JsonIgnore]
public IDictionary<string, object> Items { get; }

Property Value

IDictionary<string, object>

The request-local items collection owned by this message context.

Remarks

Request-local. Nothing in this framework serializes, persists, transmits or emits these entries. To carry a value beyond this process, mark it with SetPropagatedItem(IMessageContext, string, string) instead. The two collections are separate for the reason Activity keeps Tags and Baggage apart: whether a write crosses a trust boundary must be decided by the call, never by the spelling of a key.

Contract an implementation must keep. Returns the one collection owned by this context. Never null. The same instance on every call, for the life of the context. Mutable, and a write is observable to every subsequent read. Returning a fresh collection per call satisfies the signature and breaks this framework silently — several components write an entry through one call and read it back through another.

Message

Gets or sets the message payload.

[JsonIgnore]
public IDispatchMessage? Message { get; set; }

Property Value

IDispatchMessage

MessageDeduplicationId

Gets or sets the message deduplication ID.

[JsonPropertyName("messageDeduplicationId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? MessageDeduplicationId { get; set; }

Property Value

string

MessageGroupId

Gets or sets the message group ID for FIFO queues.

[JsonPropertyName("messageGroupId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? MessageGroupId { get; set; }

Property Value

string

MessageId

Gets or sets the unique identifier for this message instance.

[JsonPropertyName("messageId")]
public string? MessageId { get; set; }

Property Value

string

The unique identifier assigned to the message.

MessageType

Gets or sets the message type.

[JsonPropertyName("messageType")]
public string? MessageType { get; set; }

Property Value

string

MessageVersion

Gets or sets the message version.

[JsonPropertyName("messageVersion")]
public string? MessageVersion { get; set; }

Property Value

string

Metadata

Gets or sets the message metadata.

[JsonIgnore]
public IMessageMetadata? Metadata { get; set; }

Property Value

IMessageMetadata

ReceiptHandle

Gets or sets the receipt handle for cloud providers (AWS SQS, Azure Service Bus).

[JsonPropertyName("receiptHandle")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? ReceiptHandle { get; set; }

Property Value

string

ReceivedTimestampUtc

Gets or sets the received timestamp.

[JsonPropertyName("receivedTimestampUtc")]
public DateTimeOffset ReceivedTimestampUtc { get; set; }

Property Value

DateTimeOffset

RejectAsync

Gets or sets an optional rejection callback for channel-based processing.

[JsonIgnore]
public Func<string?, CancellationToken, Task>? RejectAsync { get; set; }

Property Value

Func<string, CancellationToken, Task>

Remarks

Rejection is transport I/O and therefore honors cancellation via the supplied CancellationToken.

ReplyTo

Gets or sets the reply-to address for response messages.

[JsonPropertyName("replyTo")]
public string? ReplyTo { get; set; }

Property Value

string

RequestServices

Gets or sets the scoped service provider for this message processing context.

[JsonIgnore]
public IServiceProvider RequestServices { get; set; }

Property Value

IServiceProvider

The scoped service provider for this context.

Result

Gets or sets the result of processing the message.

[JsonIgnore]
public object? Result { get; set; }

Property Value

object

The handler result or null.

RoutingDecision

Gets or sets the routing decision for the message.

[JsonIgnore]
public RoutingDecision? RoutingDecision { get; set; }

Property Value

RoutingDecision

SentTimestampUtc

Gets or sets the sent timestamp.

[JsonPropertyName("sentTimestampUtc")]
public DateTimeOffset? SentTimestampUtc { get; set; }

Property Value

DateTimeOffset?

SerializerVersion

Gets or sets the serializer version used to serialize the message.

[JsonPropertyName("serializerVersion")]
public string? SerializerVersion { get; set; }

Property Value

string

Subject

Gets or sets the message subject for legacy compatibility.

[JsonPropertyName("subject")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? Subject { get; set; }

Property Value

string

Success

Gets a value indicating whether the message processing was successful.

[JsonIgnore]
public bool Success { get; }

Property Value

bool

TenantId

Gets or sets the tenant identifier.

[JsonPropertyName("tenantId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? TenantId { get; set; }

Property Value

string

TraceParent

Gets or sets the W3C trace parent header.

[JsonPropertyName("traceParent")]
public string? TraceParent { get; set; }

Property Value

string

UserId

Gets or sets the user identifier.

[JsonPropertyName("userId")]
public string? UserId { get; set; }

Property Value

string

ValidationResult

Gets or sets the validation result for the message.

[JsonIgnore]
public IValidationResult ValidationResult { get; set; }

Property Value

IValidationResult

VersionMetadata

Gets or sets the message version metadata.

[JsonIgnore]
public IMessageVersionMetadata VersionMetadata { get; set; }

Property Value

IMessageVersionMetadata

VisibilityTimeout

Gets or sets the visibility timeout for message acknowledgment.

[JsonPropertyName("visibilityTimeout")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public DateTimeOffset? VisibilityTimeout { get; set; }

Property Value

DateTimeOffset?

Methods

Clone()

Creates a shallow copy of this envelope.

public MessageEnvelope Clone()

Returns

MessageEnvelope

A new envelope with copied values.

ContainsItem(string)

Checks if an item exists.

public bool ContainsItem(string key)

Parameters

key string

Returns

bool

Dispose()

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

public void Dispose()

GetHeader(string)

Gets a value from headers.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public string? GetHeader(string key)

Parameters

key string

The header key.

Returns

string

The header value or null if not found.

GetItem<T>(string)

Gets an item by key.

public T? GetItem<T>(string key)

Parameters

key string

Returns

T

Type Parameters

T

GetItem<T>(string, T)

Gets an item by key with a default value.

public T GetItem<T>(string key, T defaultValue)

Parameters

key string
defaultValue T

Returns

T

Type Parameters

T

RemoveItem(string)

Removes an item by key.

public void RemoveItem(string key)

Parameters

key string

Reset()

Resets the envelope to its initial state for object pooling scenarios.

public void Reset()

SetHeader(string, string?)

Sets a header value.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public void SetHeader(string key, string? value)

Parameters

key string

The header key.

value string

The header value.

SetItem<T>(string, T)

Sets an item by key.

public void SetItem<T>(string key, T value)

Parameters

key string
value T

Type Parameters

T