Table of Contents

Interface IDispatchHandler<TMessage>

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

Defines a low-level handler that returns IMessageResult directly.

public interface IDispatchHandler<in TMessage> where TMessage : IDispatchMessage

Type Parameters

TMessage

The type of message this handler processes.

Extension Methods

Examples

// For most handlers, prefer IActionHandler:
public class GetOrderHandler : IActionHandler<GetOrderAction, Order>
{
    public Task<Order> HandleAsync(GetOrderAction action, CancellationToken ct)
        => _repository.GetByIdAsync(action.OrderId, ct);
}

// Use IDispatchHandler only for advanced scenarios:
public class CachedOrderHandler : IDispatchHandler<GetOrderAction>
{
    public async Task<IMessageResult> HandleAsync(
        GetOrderAction action, IMessageContext context, CancellationToken ct)
    {
        if (_cache.TryGet(action.OrderId, out var order))
            return MessageResult.SuccessFromCache(order);
        // ...
    }
}

Remarks

For most handlers, use the specialized interfaces instead: IActionHandler<TAction>, IActionHandler<TAction, TResult>, IEventHandler<TEvent>, or IDocumentHandler<TDocument>. These return your business types directly, and the framework wraps results automatically.

Use IDispatchHandler<TMessage> only when you need:

  • Return MessageResult.SuccessFromCache(), or state another MessageDisposition on the result
  • Set ValidationResult or AuthorizationResult on success results
  • Return failure without throwing an exception
  • Access IMessageContext within the handler

Methods

HandleAsync(TMessage, IMessageContext, CancellationToken)

Handles the specified message.

Task<IMessageResult> HandleAsync(TMessage message, IMessageContext context, CancellationToken cancellationToken)

Parameters

message TMessage

The message to handle.

context IMessageContext

The message context.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IMessageResult>

The result of message processing.