Class MessageEnvelope
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
messageIDispatchMessageThe 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
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
Body
Gets or sets the message body for legacy compatibility.
[JsonPropertyName("body")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? Body { get; set; }
Property Value
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
ContentType
Gets or sets the content type.
[JsonPropertyName("contentType")]
public string? ContentType { get; set; }
Property Value
ContractVersion
Gets or sets the contract version.
[JsonPropertyName("contractVersion")]
public string? ContractVersion { get; set; }
Property Value
CorrelationId
Gets or sets the correlation identifier for tracking related messages.
[JsonPropertyName("correlationId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? CorrelationId { get; set; }
Property Value
DeadLetterErrorDescription
Gets or sets the dead letter error description.
[JsonPropertyName("deadLetterErrorDescription")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? DeadLetterErrorDescription { get; set; }
Property Value
DeadLetterReason
Gets or sets the dead letter reason.
[JsonPropertyName("deadLetterReason")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? DeadLetterReason { get; set; }
Property Value
DeliveryCount
Gets or sets the delivery count.
[JsonPropertyName("deliveryCount")]
public int DeliveryCount { get; set; }
Property Value
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
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
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
MessageDeduplicationId
Gets or sets the message deduplication ID.
[JsonPropertyName("messageDeduplicationId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? MessageDeduplicationId { get; set; }
Property Value
MessageGroupId
Gets or sets the message group ID for FIFO queues.
[JsonPropertyName("messageGroupId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? MessageGroupId { get; set; }
Property Value
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
MessageVersion
Gets or sets the message version.
[JsonPropertyName("messageVersion")]
public string? MessageVersion { get; set; }
Property Value
Metadata
Gets or sets the message metadata.
[JsonIgnore]
public IMessageMetadata? Metadata { get; set; }
Property Value
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
ReceivedTimestampUtc
Gets or sets the received timestamp.
[JsonPropertyName("receivedTimestampUtc")]
public DateTimeOffset ReceivedTimestampUtc { get; set; }
Property Value
RejectAsync
Gets or sets an optional rejection callback for channel-based processing.
[JsonIgnore]
public Func<string?, CancellationToken, Task>? RejectAsync { get; set; }
Property Value
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
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
RoutingDecision
Gets or sets the routing decision for the message.
[JsonIgnore]
public RoutingDecision? RoutingDecision { get; set; }
Property Value
SentTimestampUtc
Gets or sets the sent timestamp.
[JsonPropertyName("sentTimestampUtc")]
public DateTimeOffset? SentTimestampUtc { get; set; }
Property Value
SerializerVersion
Gets or sets the serializer version used to serialize the message.
[JsonPropertyName("serializerVersion")]
public string? SerializerVersion { get; set; }
Property Value
Subject
Gets or sets the message subject for legacy compatibility.
[JsonPropertyName("subject")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? Subject { get; set; }
Property Value
Success
Gets a value indicating whether the message processing was successful.
[JsonIgnore]
public bool Success { get; }
Property Value
TenantId
Gets or sets the tenant identifier.
[JsonPropertyName("tenantId")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? TenantId { get; set; }
Property Value
TraceParent
Gets or sets the W3C trace parent header.
[JsonPropertyName("traceParent")]
public string? TraceParent { get; set; }
Property Value
UserId
Gets or sets the user identifier.
[JsonPropertyName("userId")]
public string? UserId { get; set; }
Property Value
ValidationResult
Gets or sets the validation result for the message.
[JsonIgnore]
public IValidationResult ValidationResult { get; set; }
Property Value
VersionMetadata
Gets or sets the message version metadata.
[JsonIgnore]
public IMessageVersionMetadata VersionMetadata { get; set; }
Property Value
VisibilityTimeout
Gets or sets the visibility timeout for message acknowledgment.
[JsonPropertyName("visibilityTimeout")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public DateTimeOffset? VisibilityTimeout { get; set; }
Property Value
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
keystring
Returns
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
keystringThe 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
keystring
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
keystringdefaultValueT
Returns
- T
Type Parameters
T
RemoveItem(string)
Removes an item by key.
public void RemoveItem(string key)
Parameters
keystring
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
SetItem<T>(string, T)
Sets an item by key.
public void SetItem<T>(string key, T value)
Parameters
keystringvalueT
Type Parameters
T