Table of Contents

Class UpcastingMessageBusDecorator

Namespace
Excalibur.Dispatch.Messaging
Assembly
Excalibur.Dispatch.dll

Decorates IMessageBus to automatically upcast versioned messages before delivery to handlers.

public sealed class UpcastingMessageBusDecorator : IMessageBus
Inheritance
UpcastingMessageBusDecorator
Implements
Inherited Members
Extension Methods

Remarks

This decorator intercepts incoming messages and upcasts them to their latest registered version using the IUpcastingPipeline. This ensures handlers always receive the latest message schema version, regardless of which version was originally published.

Upcasting Behavior:

  • Events (IDispatchEvent): Upcasted before delivery to handlers
  • Actions (IDispatchAction): Pass through unchanged (commands are ephemeral)
  • Documents (IDispatchDocument): Pass through unchanged

Upcasting cost depends on message versions, the registered transformations, and the runtime configuration. Measure representative message paths; no fixed per-message or per-hop latency is guaranteed, including for messages that do not require transformation.

Thread Safety: This decorator is stateless and thread-safe as a singleton. The underlying IUpcastingPipeline handles its own thread synchronization.

Constructors

UpcastingMessageBusDecorator(IMessageBus, IUpcastingPipeline)

Initializes a new instance of the UpcastingMessageBusDecorator class.

public UpcastingMessageBusDecorator(IMessageBus inner, IUpcastingPipeline pipeline)

Parameters

inner IMessageBus

The inner message bus to decorate.

pipeline IUpcastingPipeline

The upcasting pipeline for version transformation.

Exceptions

ArgumentNullException

Thrown when inner or pipeline is null.

Methods

PublishAsync(IDispatchAction, IMessageContext, CancellationToken)

Publishes an action message to the message bus without upcasting.

public Task PublishAsync(IDispatchAction action, IMessageContext context, CancellationToken cancellationToken)

Parameters

action IDispatchAction

The action to publish.

context IMessageContext

The message context containing metadata and routing information.

cancellationToken CancellationToken

The cancellation token to observe.

Returns

Task

A task representing the asynchronous publish operation.

Remarks

Actions (commands) are ephemeral and pass through unchanged. The producer is expected to send the current version, and handlers should be updated to accept the latest schema.

PublishAsync(IDispatchDocument, IMessageContext, CancellationToken)

Publishes a document message to the message bus without upcasting.

public Task PublishAsync(IDispatchDocument doc, IMessageContext context, CancellationToken cancellationToken)

Parameters

doc IDispatchDocument

The document to publish.

context IMessageContext

The message context containing metadata and routing information.

cancellationToken CancellationToken

The cancellation token to observe.

Returns

Task

A task representing the asynchronous publish operation.

Remarks

Documents pass through unchanged. Document versioning, if needed, should be handled at the application layer through explicit transformation.

PublishAsync(IDispatchEvent, IMessageContext, CancellationToken)

Publishes an event message to the message bus, upcasting if necessary.

public Task PublishAsync(IDispatchEvent evt, IMessageContext context, CancellationToken cancellationToken)

Parameters

evt IDispatchEvent

The event to publish.

context IMessageContext

The message context containing metadata and routing information.

cancellationToken CancellationToken

The cancellation token to observe.

Returns

Task

A task representing the asynchronous publish operation.

Remarks

Integration events may arrive from external systems in older versions. This method upcasts versioned events to the latest registered version before delivering to handlers.

If the event does not implement IVersionedMessage, or if it is already at the latest version, it passes through with minimal overhead.

See Also