Class DispatchMiddlewareBase
- Namespace
- Excalibur.Dispatch.Middleware
- Assembly
- Excalibur.Dispatch.dll
Provides a base implementation for dispatch middleware with allocation-free patterns.
public abstract class DispatchMiddlewareBase : IDispatchMiddleware
- Inheritance
-
DispatchMiddlewareBase
- Implements
- Inherited Members
- Extension Methods
Remarks
This abstract class provides a foundation for creating middleware components with minimal allocations. It implements common patterns and provides virtual methods for customization. Derived classes should override the ProcessAsync method to implement their specific logic.
Properties
ApplicableMessageKinds
Gets the message kinds that this middleware applies.
public virtual MessageKinds ApplicableMessageKinds { get; }
Property Value
- MessageKinds
The set of message kinds this middleware applies to.
Remarks
Specifies which types of messages this middleware should process. The pipeline filters middleware based on these flags, ensuring only relevant middleware processes each message. This improves performance and allows middleware to specialize in handling specific message types. If not implemented, defaults to All for backward compatibility.
RequiredFeatures
public virtual IReadOnlyCollection<string>? RequiredFeatures { get; }
Property Value
Stage
Gets the pipeline stage where this middleware should execute.
public virtual DispatchMiddlewareStage? Stage { get; }
Property Value
- DispatchMiddlewareStage?
The pipeline stage for this middleware.
Remarks
The stage determines the execution order of middleware in the pipeline. If null, the middleware will be registered at the end of the pipeline. Stages are processed in numeric order, allowing fine-grained control over middleware execution sequence.
Methods
InvokeAsync(IDispatchMessage, IMessageContext, DispatchRequestDelegate, CancellationToken)
Processes the message within the middleware pipeline.
public ValueTask<IMessageResult> InvokeAsync(IDispatchMessage message, IMessageContext context, DispatchRequestDelegate nextDelegate, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message being processed.
contextIMessageContextThe message context containing metadata and processing state.
nextDelegateDispatchRequestDelegateThe delegate to invoke the next middleware in the pipeline.
cancellationTokenCancellationTokenThe cancellation token to observe.
Returns
- ValueTask<IMessageResult>
A ValueTask<TResult> representing the result of message processing, potentially modified by this middleware. ValueTask can avoid allocating a Task for a synchronously completed result; other dispatch work can still allocate.
Remarks
Implementations can execute logic before calling nextDelegate, after calling it, or both. To short-circuit the pipeline, don't call nextDelegate and return an appropriate result. The context can be used to share data between middleware components. Respect the cancellation token to support timeouts and graceful shutdown.
Exceptions
- ArgumentNullException
Thrown when message, context, or nextDelegate is null.
- OperationCanceledException
Thrown when the operation is cancelled.
OnAfterProcessAsync(IDispatchMessage, IMessageContext, IMessageResult, CancellationToken)
Called after processing the message.
protected virtual ValueTask<IMessageResult?> OnAfterProcessAsync(IDispatchMessage message, IMessageContext context, IMessageResult result, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message that was processed.
contextIMessageContextThe message context.
resultIMessageResultThe processing result.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- ValueTask<IMessageResult>
A modified result, or null to use the original result.
OnBeforeProcessAsync(IDispatchMessage, IMessageContext, CancellationToken)
Called before processing the message.
protected virtual ValueTask<IMessageResult?> OnBeforeProcessAsync(IDispatchMessage message, IMessageContext context, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message being processed.
contextIMessageContextThe message context.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- ValueTask<IMessageResult>
A result to short-circuit processing, or null to continue.
OnErrorAsync(IDispatchMessage, IMessageContext, Exception, CancellationToken)
Called when an error occurs during processing.
protected virtual ValueTask<IMessageResult?> OnErrorAsync(IDispatchMessage message, IMessageContext context, Exception exception, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message being processed.
contextIMessageContextThe message context.
exceptionExceptionThe exception that occurred.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- ValueTask<IMessageResult>
A result to handle the error, or null to rethrow.
ProcessAsync(IDispatchMessage, IMessageContext, DispatchRequestDelegate, CancellationToken)
Processes the message through the middleware logic.
protected virtual ValueTask<IMessageResult> ProcessAsync(IDispatchMessage message, IMessageContext context, DispatchRequestDelegate nextDelegate, CancellationToken cancellationToken)
Parameters
messageIDispatchMessageThe message being processed.
contextIMessageContextThe message context.
nextDelegateDispatchRequestDelegateThe next middleware delegate.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- ValueTask<IMessageResult>
The processing result.
ShouldProcess(IDispatchMessage, IMessageContext)
Determines whether this middleware should process the given message.
protected virtual bool ShouldProcess(IDispatchMessage message, IMessageContext context)
Parameters
messageIDispatchMessageThe message to evaluate.
contextIMessageContextThe message context.
Returns
- bool
True if the message should be processed; otherwise, false.