Table of Contents

Interface IMessageBus

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

Provides an abstraction for publishing messages to the underlying messaging infrastructure.

public interface IMessageBus
Extension Methods

Remarks

The message bus is responsible for routing messages to their appropriate destinations, which may be in-process handlers, message queues, or remote services. Implementations handle serialization, transport, and delivery guarantees. Key responsibilities include:

  • Message serialization and envelope creation
  • Transport-specific protocol handling
  • Routing based on message type and configuration
  • Delivery guarantees (at-least-once, at-most-once, exactly-once)
  • Integration with various message brokers (RabbitMQ, Kafka, Azure Service Bus, etc.)

The message bus is typically accessed through IDispatcher rather than directly. Multiple message bus implementations can be registered for different transports.

Methods

PublishAsync(IDispatchAction, IMessageContext, CancellationToken)

Publishes an action message to the message bus.

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 are typically routed to a single handler. For request-reply patterns, the context.ReplyTo property indicates where responses should be sent. The implementation ensures the message is durably queued or delivered.

Exceptions

ArgumentNullException

Thrown when action or context is null.

InvalidOperationException

Thrown when the message bus is not properly configured.

PublishAsync(IDispatchDocument, IMessageContext, CancellationToken)

Publishes a document message to the message bus.

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 may be routed to multiple handlers for processing different aspects. Large documents may be chunked or use claim-check patterns depending on the transport limitations and configuration.

Exceptions

ArgumentNullException

Thrown when doc or context is null.

InvalidOperationException

Thrown when the message bus is not properly configured.

PublishAsync(IDispatchEvent, IMessageContext, CancellationToken)

Publishes an event message to the message bus.

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

Events are typically published to multiple subscribers using pub-sub patterns. The implementation handles fan-out to all registered event handlers. For integration events, the context may specify external endpoints.

All handlers for a single published event observe the same scoped service instances. One dependency-injection scope is created per published event — not one per handler — and it is disposed only after every handler has completed. Two handlers for the same event therefore share the same IUnitOfWork or DbContext, so one event is handled as one unit of work. Separate publishes get separate scopes, and no scope is created at all when no handler for the event depends on a scoped service.

Faults are isolated between handlers; state is not. Every handler is started and awaited, so one handler throwing does not prevent the others from running — but because they share scoped instances, a handler that fails after leaving a shared service in a broken state hands that state to the siblings that run after it. If a handler must not be affected by a sibling's failure, resolve its dependency from a factory rather than the shared scope, or give it its own message.

Which exception you catch does not depend on how many handlers are registered. When exactly one handler fails, that handler's own exception is rethrown with its original stack trace, whether one handler was subscribed or ten. Only a genuine multi-fault fan-out — two or more handlers failing for the same published event — throws AggregateException, whose InnerExceptions carries every fault. This is the same unwrapping rule as Task.GetAwaiter().GetResult().

The guarantee matters because a catch block, an exception mapper, and a typed exception handler all select on the exception's type. Were a sole fault wrapped, subscribing a second handler would silently stop the consumer's handling of the first one's exception. Consumers that must also handle the multi-fault case should catch AggregateException in addition to their own type.

Exceptions

ArgumentNullException

Thrown when evt or context is null.

InvalidOperationException

Thrown when the message bus is not properly configured.

AggregateException

Thrown when two or more handlers fail while publishing the event; every fault is in InnerExceptions. A single failing handler rethrows its own exception instead, regardless of how many handlers are subscribed.

See Also