Table of Contents

Class DispatcherContextExtensions

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.dll

Extension methods for IDispatcher that provide context-aware dispatch operations. These methods automatically use the current ambient context or create a new one if none exists.

public static class DispatcherContextExtensions
Inheritance
DispatcherContextExtensions
Inherited Members

Methods

DispatchAsync<TResponse>(IDispatcher, IDispatchAction<TResponse>, IMessageContext, CancellationToken)

Dispatches an action with an inferred response type using an explicit message context. The compiler infers TResponse from the IDispatchAction<TResponse> parameter.

[UnconditionalSuppressMessage("AOT", "IL2026:RequiresUnreferencedCode", Justification = "Source-generated typed overloads in TypedDispatchExtensions shadow this method via C# overload resolution when Excalibur.Dispatch.SourceGenerators is referenced (required for AOT).")]
[UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "Source-generated typed overloads in TypedDispatchExtensions shadow this method via C# overload resolution when Excalibur.Dispatch.SourceGenerators is referenced (required for AOT).")]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Task<IMessageResult<TResponse>> DispatchAsync<TResponse>(this IDispatcher dispatcher, IDispatchAction<TResponse> message, IMessageContext context, CancellationToken cancellationToken)

Parameters

dispatcher IDispatcher

The dispatcher instance.

message IDispatchAction<TResponse>

The action to dispatch. Must implement IDispatchAction<TResponse>.

context IMessageContext

The message context for the dispatch operation.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IMessageResult<TResponse>>

A task representing the dispatch result with the typed response.

Type Parameters

TResponse

The response type, inferred from the action's interface.

Remarks

This overload enables clean call sites with explicit context without type parameters:

var result = await dispatcher.DispatchAsync(command, context, ct);

Performance: Same caching behavior as the context-free overload. See DispatchAsync<TResponse>(IDispatcher, IDispatchAction<TResponse>, CancellationToken) for details.

Exceptions

ArgumentNullException

Thrown when dispatcher or context is null.

DispatchAsync<TResponse>(IDispatcher, IDispatchAction<TResponse>, CancellationToken)

Dispatches an action with an inferred response type. The compiler infers TResponse from the IDispatchAction<TResponse> parameter, eliminating the need for explicit type arguments at the call site.

[UnconditionalSuppressMessage("AOT", "IL2026:RequiresUnreferencedCode", Justification = "Source-generated typed overloads in TypedDispatchExtensions shadow this method via C# overload resolution when Excalibur.Dispatch.SourceGenerators is referenced (required for AOT).")]
[UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "Source-generated typed overloads in TypedDispatchExtensions shadow this method via C# overload resolution when Excalibur.Dispatch.SourceGenerators is referenced (required for AOT).")]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Task<IMessageResult<TResponse>> DispatchAsync<TResponse>(this IDispatcher dispatcher, IDispatchAction<TResponse> message, CancellationToken cancellationToken)

Parameters

dispatcher IDispatcher

The dispatcher instance.

message IDispatchAction<TResponse>

The action to dispatch. Must implement IDispatchAction<TResponse>.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IMessageResult<TResponse>>

A task representing the dispatch result with the typed response.

Type Parameters

TResponse

The response type, inferred from the action's interface.

Remarks

This overload enables clean call sites without explicit type parameters:

// Instead of: dispatcher.DispatchAsync<CreateOrderCommand, Guid>(command, ct)
var result = await dispatcher.DispatchAsync(command, ct);

Performance: The first call per concrete message type incurs a one-time reflection cost to build a cached delegate. Subsequent calls use the cached delegate with near-zero overhead. When the Excalibur.Dispatch.SourceGenerators package is referenced, the source generator emits concrete typed overloads that shadow this method via C# overload resolution, providing zero-reflection dispatch with full AOT compatibility.

Exceptions

ArgumentNullException

Thrown when dispatcher is null.

DispatchAsync<TMessage>(IDispatcher, TMessage, CancellationToken)

Dispatches a message using the current ambient context or a new context if none exists.

[UnconditionalSuppressMessage("AOT", "IL2026:RequiresUnreferencedCode", Justification = "Dispatch selects AOT-safe handler invocation (HandlerInvokerAot) when dynamic code is not supported.")]
[UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "Dispatch selects AOT-safe handler invocation (HandlerInvokerAot) when dynamic code is not supported.")]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Task<IMessageResult> DispatchAsync<TMessage>(this IDispatcher dispatcher, TMessage message, CancellationToken cancellationToken) where TMessage : IDispatchMessage

Parameters

dispatcher IDispatcher

The dispatcher instance.

message TMessage

The message to dispatch.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IMessageResult>

A task representing the dispatch result.

Type Parameters

TMessage

The type of message to dispatch.

Remarks

When called from within a handler (where an ambient context exists), this method dispatches a child by default — a fresh MessageId with CausationId set to the parent's message id, propagating correlation, identity, and routing — mirroring Activity/OpenTelemetry StartActivity. For top-level dispatches (no ambient context) a fresh root context is created. To deliberately reuse the same context instead of childing, pass it explicitly to the DispatchAsync<TMessage>(TMessage, IMessageContext, CancellationToken) overload.

Exceptions

ArgumentNullException

Thrown when dispatcher is null.

DispatchAsync<TMessage, TResponse>(IDispatcher, TMessage, CancellationToken)

Dispatches an action and returns the response using the current ambient context or a new context if none exists.

[UnconditionalSuppressMessage("AOT", "IL2026:RequiresUnreferencedCode", Justification = "Dispatch selects AOT-safe handler invocation (HandlerInvokerAot) when dynamic code is not supported.")]
[UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "Dispatch selects AOT-safe handler invocation (HandlerInvokerAot) when dynamic code is not supported.")]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Task<IMessageResult<TResponse>> DispatchAsync<TMessage, TResponse>(this IDispatcher dispatcher, TMessage message, CancellationToken cancellationToken) where TMessage : IDispatchAction<TResponse>

Parameters

dispatcher IDispatcher

The dispatcher instance.

message TMessage

The action to dispatch.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IMessageResult<TResponse>>

A task representing the dispatch result with response.

Type Parameters

TMessage

The type of action to dispatch.

TResponse

The type of response expected.

Remarks

When called from within a handler (where an ambient context exists), this method dispatches a child by default — a fresh MessageId with CausationId set to the parent's message id, propagating correlation, identity, and routing — mirroring Activity/OpenTelemetry StartActivity. For top-level dispatches (no ambient context) a fresh root context is created. To deliberately reuse the same context instead of childing, pass it explicitly to the DispatchAsync<TMessage, TResponse>(TMessage, IMessageContext, CancellationToken) overload.

Exceptions

ArgumentNullException

Thrown when dispatcher is null.