Table of Contents

Interface IMessageMetadata

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

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, TenantId
  • MetadataVersioningExtensions -- ContentEncoding, MessageVersion, SerializerVersion, ContractVersion
  • MetadataRoutingExtensions -- Destination, ReplyTo, SessionId, PartitionKey, RoutingKey, GroupId, GroupSequence
  • MetadataTemporalExtensions -- SentTimestampUtc, ReceivedTimestampUtc, ScheduledEnqueueTimeUtc, TimeToLive, ExpiresAtUtc
  • MetadataTransportExtensions -- DeliveryCount, MaxDeliveryCount, DeadLetter*, Priority, Durable, DuplicateDetection
  • MetadataEventSourcingExtensions -- 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

string

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

string

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

string

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

DateTimeOffset

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

IReadOnlyDictionary<string, string>

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

string

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

string

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

IReadOnlyDictionary<string, object>

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

string

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.