Interface IMessageBus
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
actionIDispatchActionThe action to publish.
contextIMessageContextThe message context containing metadata and routing information.
cancellationTokenCancellationTokenThe 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
docIDispatchDocumentThe document to publish.
contextIMessageContextThe message context containing metadata and routing information.
cancellationTokenCancellationTokenThe 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
evtIDispatchEventThe event to publish.
contextIMessageContextThe message context containing metadata and routing information.
cancellationTokenCancellationTokenThe 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.