Interface IMessageMetadata
Core interface for message metadata across the Excalibur framework. Contains only the essential envelope fields needed for dispatching and correlation. Domain-specific metadata (identity, routing, temporal, transport, event sourcing) is accessed via extension methods on the Properties dictionary.
public interface IMessageMetadata
- Extension Methods
Remarks
This minimal interface follows the Microsoft design pattern of keeping interfaces small (max 5 methods + properties bag)
and using extension methods for optional/domain-specific concerns. Properties that were previously on this interface
are now available through typed extension methods in Excalibur.Dispatch.Metadata:
MetadataIdentityExtensions-- ExternalId, TraceParent, TraceState, Baggage, UserId, Roles, Claims, TenantIdMetadataVersioningExtensions-- ContentEncoding, MessageVersion, SerializerVersion, ContractVersionMetadataRoutingExtensions-- Destination, ReplyTo, SessionId, PartitionKey, RoutingKey, GroupId, GroupSequenceMetadataTemporalExtensions-- SentTimestampUtc, ReceivedTimestampUtc, ScheduledEnqueueTimeUtc, TimeToLive, ExpiresAtUtcMetadataTransportExtensions-- DeliveryCount, MaxDeliveryCount, DeadLetter*, Priority, Durable, DuplicateDetectionMetadataEventSourcingExtensions-- AggregateId, AggregateType, AggregateVersion, Stream*, GlobalPosition, EventType, EventVersion
Implementations should ensure thread-safety for concurrent access scenarios.
Properties
CausationId
Gets the identifier of the message that caused this message to be created.
string? CausationId { get; init; }
Property Value
Remarks
Forms a causality chain for debugging. May be null for root messages that were not caused by another message.
ContentType
Gets the MIME type of the message payload serialization format.
string ContentType { get; init; }
Property Value
Remarks
Common values include "application/json", "application/x-msgpack", "application/x-protobuf", or "application/octet-stream". Used to select the appropriate deserializer.
CorrelationId
Gets the correlation identifier that groups related messages together.
string CorrelationId { get; init; }
Property Value
Remarks
Flows through all messages in a business transaction or workflow, enabling end-to-end tracing across service boundaries.
CreatedTimestampUtc
Gets the UTC timestamp when this message was created.
DateTimeOffset CreatedTimestampUtc { get; init; }
Property Value
Remarks
Set by the sender to indicate when the message was originally created. Should always be in UTC to avoid timezone issues.
Headers
Gets the collection of custom headers for this message.
IReadOnlyDictionary<string, string> Headers { get; init; }
Property Value
Remarks
Used for provider-specific metadata that doesn't fit standard fields. Common in HTTP-based transports and cloud provider implementations. Implementations should return an empty dictionary rather than null.
MessageId
Gets the unique identifier for this message instance.
string MessageId { get; init; }
Property Value
Remarks
This ID uniquely identifies a specific message and should remain constant through retries and redeliveries. Typically a GUID or UUID7.
MessageType
Gets the fully qualified type name of the message.
string MessageType { get; init; }
Property Value
Remarks
Contains the CLR type name for deserialization and routing. Format is typically "Namespace.TypeName, AssemblyName".
Properties
Gets the collection of custom properties for extensible metadata storage.
IReadOnlyDictionary<string, object> Properties { get; init; }
Property Value
Remarks
General-purpose extension point for additional metadata. Domain-specific metadata (identity, routing, temporal, transport, event sourcing) is stored here and accessed via typed extension methods. Implementations should return an empty dictionary rather than null.
Source
Gets the source system or service that originated this message.
string? Source { get; init; }
Property Value
Remarks
Typically contains the service name, application name, or endpoint that created the message. Useful for debugging and monitoring.
Methods
ToBuilder()
Creates a mutable builder from this metadata instance.
IMessageMetadataBuilder ToBuilder()
Returns
- IMessageMetadataBuilder
A builder that can be used to create a modified copy of this metadata.