Class DispatcherContextExtensions
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
dispatcherIDispatcherThe dispatcher instance.
messageIDispatchAction<TResponse>The action to dispatch. Must implement IDispatchAction<TResponse>.
contextIMessageContextThe message context for the dispatch operation.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IMessageResult<TResponse>>
A task representing the dispatch result with the typed response.
Type Parameters
TResponseThe 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
dispatcherorcontextis 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
dispatcherIDispatcherThe dispatcher instance.
messageIDispatchAction<TResponse>The action to dispatch. Must implement IDispatchAction<TResponse>.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IMessageResult<TResponse>>
A task representing the dispatch result with the typed response.
Type Parameters
TResponseThe 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
dispatcheris 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
dispatcherIDispatcherThe dispatcher instance.
messageTMessageThe message to dispatch.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IMessageResult>
A task representing the dispatch result.
Type Parameters
TMessageThe 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
dispatcheris 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
dispatcherIDispatcherThe dispatcher instance.
messageTMessageThe action to dispatch.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IMessageResult<TResponse>>
A task representing the dispatch result with response.
Type Parameters
TMessageThe type of action to dispatch.
TResponseThe 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
dispatcheris null.