Class RetryMiddleware
- Namespace
- Excalibur.Dispatch.Middleware.Resilience
- Assembly
- Excalibur.Dispatch.dll
Middleware that implements retry logic for failed message processing.
[AppliesTo(MessageKinds.All)]
public sealed class RetryMiddleware : IDispatchMiddleware
- Inheritance
-
RetryMiddleware
- Implements
- Inherited Members
- Extension Methods
Remarks
This middleware decides how many attempts a fault gets, and nothing else about it. A fault it declines to retry is raised after one attempt, and a transient one after the configured attempts — in both cases the original exception propagates with its type and message intact, so an exception mapper or typed exception handler registered above still matches on the exception the handler actually threw.
When the downstream returns failed results rather than throwing, exhaustion returns the last of those results unchanged: there is no exception to raise, and the failure the pipeline below produced is what the caller should see.
Constructors
RetryMiddleware(IOptions<RetryOptions>, ITelemetrySanitizer, ILogger<RetryMiddleware>, IMessageFailureClassifier?)
Middleware that implements retry logic for failed message processing.
public RetryMiddleware(IOptions<RetryOptions> options, ITelemetrySanitizer sanitizer, ILogger<RetryMiddleware> logger, IMessageFailureClassifier? classifier = null)
Parameters
optionsIOptions<RetryOptions>The retry options.
sanitizerITelemetrySanitizerThe telemetry sanitizer for PII protection.
loggerILogger<RetryMiddleware>The logger.
classifierIMessageFailureClassifierOptional shared failure classifier used to decide whether an unfiltered exception is retryable. If null, defaults to Excalibur.Dispatch.Resilience.DefaultMessageFailureClassifier.
Remarks
This middleware decides how many attempts a fault gets, and nothing else about it. A fault it declines to retry is raised after one attempt, and a transient one after the configured attempts — in both cases the original exception propagates with its type and message intact, so an exception mapper or typed exception handler registered above still matches on the exception the handler actually threw.
When the downstream returns failed results rather than throwing, exhaustion returns the last of those results unchanged: there is no exception to raise, and the failure the pipeline below produced is what the caller should see.
Properties
Stage
Gets the pipeline stage where this middleware should execute.
public 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.