Table of Contents

Class RetryOptions

Namespace
Excalibur.Dispatch.Options.Resilience
Assembly
Excalibur.Dispatch.dll

Configuration options for retry behavior across the Excalibur framework.

public sealed class RetryOptions
Inheritance
RetryOptions
Inherited Members
Extension Methods

Remarks

This is the canonical retry options class for core retry logic. It consolidates retry configuration from Options.Core, Options.Middleware, and Transport.Abstractions.ServiceMesh.

For Polly-specific retry options with advanced features like JitterStrategy, OperationTimeout, and custom ShouldRetry predicates, use Excalibur.Dispatch.Resilience.Polly.PollyRetryOptions instead.

Properties

BackoffMultiplier

Gets or sets the backoff multiplier for exponential backoff.

public double BackoffMultiplier { get; set; }

Property Value

double

Default is 2.0 (doubles delay each retry).

BackoffStrategy

Gets or sets the backoff strategy for calculating retry delays.

public BackoffStrategy BackoffStrategy { get; set; }

Property Value

BackoffStrategy

Default is Exponential.

BaseDelay

Gets or sets the base delay between retry attempts.

public TimeSpan BaseDelay { get; set; }

Property Value

TimeSpan

Default is 1 second.

MaxDelay

Gets or sets the maximum delay between retry attempts.

public TimeSpan MaxDelay { get; set; }

Property Value

TimeSpan

Default is 30 seconds.

MaxRetryAttempts

Gets or sets the maximum number of retry attempts after the initial attempt fails.

public int MaxRetryAttempts { get; set; }

Property Value

int

Default is 3 (1 initial attempt + 3 retries = 4 total attempts).

NonRetryableExceptions

Gets the exception types that should not trigger retries.

public HashSet<Type> NonRetryableExceptions { get; }

Property Value

HashSet<Type>

The set of exceptions that bypass retry logic.

Remarks

These exceptions are considered non-transient and will not be retried, regardless of the RetryableExceptions configuration.

RetryableExceptions

Gets the exception types that should trigger retries.

public HashSet<Type> RetryableExceptions { get; }

Property Value

HashSet<Type>

The set of exceptions eligible for retries.

Remarks

If empty, no allowlist is applied and the shared failure classifier decides: only exceptions it classifies as transient are retried. Permanent and poison faults — deserialization, validation, argument and authorization failures — are abandoned after the first attempt, not retried. NonRetryableExceptions is checked first either way and always wins.

UseJitter

Gets or sets a value indicating whether to add jitter to retry delays.

public bool UseJitter { get; set; }

Property Value

bool

true to randomize retry delays; otherwise, false. Default is false.

Remarks

Jitter prevents the thundering herd: clients that failed together would otherwise retry together. When enabled, the delay is sampled uniformly from zero up to the value the configured BackoffStrategy prescribes, so it never exceeds that value and may be well below it. Sampling the low end is the property that decorrelates clients; a band around the nominal delay adds noise without spreading them.

Applies to every strategy. It used to be read by only one of them while the others decided jitter for themselves, so a configuration could request jitter and silently receive none. It is now the single switch, and BackoffStrategy names only the growth law.

Defaults to false, which is the default Polly's own RetryStrategyOptions.UseJitter uses. Jitter is worth enabling for any workload where several instances can fail at the same moment.