Table of Contents

Class CircuitBreakerOptions

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

Configuration options for circuit breaker.

public sealed class CircuitBreakerOptions
Inheritance
CircuitBreakerOptions
Inherited Members
Extension Methods

Remarks

This is the canonical CircuitBreakerOptions for the Excalibur framework, consolidating Options.Middleware.CircuitBreakerOptions.

For per-service mesh configurations with callbacks, see Excalibur.Dispatch.Transport.Abstractions.ServiceMesh.CircuitBreakerOptions.

Properties

BreakDuration

Gets or sets the duration to keep the circuit open before the next probe.

public TimeSpan BreakDuration { get; set; }

Property Value

TimeSpan

Default is 30 seconds.

Remarks

Must be between 500ms and 1 day, enforced by the validator for the reason given on SamplingDuration.

CircuitKeySelector

Gets or sets the function to determine the circuit key for a message.

public Func<IDispatchMessage, string>? CircuitKeySelector { get; set; }

Property Value

Func<IDispatchMessage, string>

Default is null (uses message type name).

Remarks

When set, this function is used to determine which circuit a message belongs to, enabling per-message-type circuit isolation. If null, the message type name is used as the circuit key.

ConsecutiveFailureThreshold

Gets or sets the number of consecutive failures that opens the circuit.

[Range(1, 2147483647)]
public int ConsecutiveFailureThreshold { get; set; }

Property Value

int

Default is 5.

Remarks

Read by count-based providers, which open as soon as this many failures occur in a row and reset the run on any success. A value of 1 opens the circuit on the first failure. Ratio-based providers ignore this and use MinimumThroughput with FailureRatio instead.

FailureRatio

Gets or sets the proportion of failed calls within SamplingDuration that opens the circuit.

[Range(0, 1)]
public double FailureRatio { get; set; }

Property Value

double

Default is 0.5 (50% of observed calls).

Remarks

Used only by ratio-based providers, and only once MinimumThroughput calls have been observed within the sampling window. Count-based providers ignore this value because they open on a consecutive-failure count instead. A value of 1.0 requires every observed call in the window to have failed.

MinimumThroughput

Gets or sets the number of calls that must be observed within SamplingDuration before FailureRatio is evaluated.

[Range(2, 2147483647)]
public int MinimumThroughput { get; set; }

Property Value

int

Default is 5.

Remarks

Read by ratio-based providers. Below this many observed calls the circuit stays closed however many of them failed, so a burst of failures early in a window does not trip it. At least two calls are required for a ratio to be meaningful. Count-based providers ignore this and use ConsecutiveFailureThreshold instead.

OperationTimeout

Gets or sets the timeout applied to individual operations executed under the circuit breaker.

public TimeSpan OperationTimeout { get; set; }

Property Value

TimeSpan

Default is 5 seconds.

Remarks

Must be between 10ms and 1 day — the provider's timeout strategy has a lower floor than the circuit windows above. Enforced by the validator, for the reason given on SamplingDuration.

SamplingDuration

Gets or sets the rolling window over which FailureRatio is measured.

public TimeSpan SamplingDuration { get; set; }

Property Value

TimeSpan

Default is 30 seconds.

Remarks

Used only by ratio-based providers; count-based providers ignore it. Ratio-based providers require a window of at least 500 milliseconds.

Must be between 500ms and 1 day: the value is forwarded verbatim to the resilience provider, which enforces that range itself and would otherwise reject it when the pipeline is built.

The bound is enforced in CircuitBreakerOptionsValidator rather than by a [Range] attribute, and deliberately so. The only RangeAttribute overload that accepts a TimeSpan takes (Type, string, string) and parses via a TypeConverter, which carries RequiresUnreferencedCode; this package treats IL2026 as an error, so adding the attribute trades an AOT-honesty regression for a duplicate of a check the validator already performs. The int-typed siblings above can use the attribute because their overload needs no converter.