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.