Class ShieldBuilder
- Namespace
- Kevlar
- Assembly
- Kevlar.dll
An immutable exception-handling clause under construction for a Shield chain.
Obtained via Shield.When<T>() or shield.When<T>(); finished by adding a
strategy. The clause becomes the shield's ambient handling: it applies to the strategy added
here and to reactive strategies chained afterwards, until replaced by a new clause.
public sealed class ShieldBuilder- Inheritance
-
ShieldBuilder
- Inherited Members
Remarks
Start a clause with When… on a shield, then continue it with Or… on this builder:
Shield.When<A>().Or<B>().Retry(3).
The builder is immutable. Each Or… returns a new builder holding the terms
accumulated so far plus the one just added, and leaves the builder it was called on untouched.
A builder held in a variable can therefore be branched into two chains safely: each branch gets
only its own terms. The corollary is that code must use the builder each Or…
returns — calling Or… and discarding the result adds nothing to anything.
Adding a strategy freezes the clause of that builder, so a shield already built is never
changed by further chaining either.
One strategy can opt out of the ambient clause: setting HandlesException on its options
(RetryOptions, CircuitBreakerOptions, HedgeOptions,
FallbackOptions) makes that strategy ignore the clause and handle only what its
own predicate selects. Every other strategy in the chain keeps using the ambient clause.
Methods
CircuitBreaker(Action<CircuitBreakerOptions>)
Adds a circuit breaker strategy configured via configure.
public Shield CircuitBreaker(Action<CircuitBreakerOptions> configure)Parameters
configureAction<CircuitBreakerOptions>
Returns
CircuitBreaker(int, TimeSpan)
Breaks the circuit for breakDuration after consecutiveFailures consecutive handled exceptions.
public Shield CircuitBreaker(int consecutiveFailures, TimeSpan breakDuration)Parameters
Returns
ConcurrencyLimit(Action<ConcurrencyLimitOptions>)
Adds a configured concurrency limit. The handling clauses remain ambient for later strategies.
public Shield ConcurrencyLimit(Action<ConcurrencyLimitOptions> configure)Parameters
configureAction<ConcurrencyLimitOptions>
Returns
ConcurrencyLimit(int, int)
Caps concurrency. The handling clauses remain ambient for later strategies.
public Shield ConcurrencyLimit(int maxConcurrency, int queueLimit = 0)Parameters
Returns
Fallback(Func<Exception, CancellationToken, ValueTask>)
Runs fallback in place of handled failures. Applies to void executions
only; result-producing recovery needs Shield.For<T>().FallbackTo(…) for a constant
value or a typed Fallback(…) factory.
public Shield Fallback(Func<Exception, CancellationToken, ValueTask> fallback)Parameters
fallbackFunc<Exception, CancellationToken, ValueTask>
Returns
Fallback(Func<Exception, CancellationToken, ValueTask>, Action<FallbackOptions>)
Runs fallback in place of handled failures and configures notifications.
Applies to void executions only.
public Shield Fallback(Func<Exception, CancellationToken, ValueTask> fallback, Action<FallbackOptions> configure)Parameters
fallbackFunc<Exception, CancellationToken, ValueTask>configureAction<FallbackOptions>
Returns
Fallback(Func<CancellationToken, ValueTask>)
Runs fallback in place of handled failures. Applies to void executions
only; result-producing recovery needs a typed shield.
public Shield Fallback(Func<CancellationToken, ValueTask> fallback)Parameters
fallbackFunc<CancellationToken, ValueTask>
Returns
Fallback(Func<CancellationToken, ValueTask>, Action<FallbackOptions>)
Runs fallback in place of handled failures and configures notifications.
Applies to void executions only.
public Shield Fallback(Func<CancellationToken, ValueTask> fallback, Action<FallbackOptions> configure)Parameters
fallbackFunc<CancellationToken, ValueTask>configureAction<FallbackOptions>
Returns
Hedge(Action<HedgeOptions>)
Adds a hedging strategy configured via configure.
public Shield Hedge(Action<HedgeOptions> configure)Parameters
configureAction<HedgeOptions>
Returns
Remarks
Hedging on an untyped Shield runs the execution delegate more than once,
concurrently, so the delegate must be idempotent. Prefer Shield.For<T>(), or
confirm the action is safe to repeat.
Hedge(int, TimeSpan)
Races concurrent attempts; a handled exception launches the next attempt immediately.
public Shield Hedge(int maxHedgedAttempts, TimeSpan delay)Parameters
Returns
Remarks
Hedging on an untyped Shield runs the execution delegate more than once,
concurrently, and only its exceptions can select a winner. The delegate must therefore be
idempotent: duplicate writes, charges, or sends are otherwise observable side effects of a
hedge that later loses. Prefer Shield.For<T>(), where result clauses decide which
attempt is acceptable, or confirm the action is safe to repeat.
Or(Func<Exception, bool>)
Returns a new builder that also handles exceptions matching predicate, whatever their type.
public ShieldBuilder Or(Func<Exception, bool> predicate)Parameters
Returns
OrContext(Func<HandlingEvent, bool>)
Returns a new builder that also handles exceptions selected using execution context.
public ShieldBuilder OrContext(Func<HandlingEvent, bool> predicate)Parameters
predicateFunc<HandlingEvent, bool>
Returns
OrInner<TException>()
Returns a new builder that also handles exceptions containing an exception of type TException.
public ShieldBuilder OrInner<TException>() where TException : ExceptionReturns
Type Parameters
TException
Remarks
The outer exception, ordinary inner-exception chains, and every branch of an AggregateException are searched.
OrInner<TException>(Func<TException, bool>)
Returns a new builder that also handles exceptions containing an exception of type TException matching predicate.
public ShieldBuilder OrInner<TException>(Func<TException, bool> predicate) where TException : ExceptionParameters
Returns
Type Parameters
TException
Remarks
The outer exception, ordinary inner-exception chains, and every branch of an AggregateException are searched.
Or<TException>()
Returns a new builder that also handles exceptions of type TException.
public ShieldBuilder Or<TException>() where TException : ExceptionReturns
Type Parameters
TException
Or<TException>(Func<TException, bool>)
Returns a new builder that also handles exceptions of type TException matching predicate.
public ShieldBuilder Or<TException>(Func<TException, bool> predicate) where TException : ExceptionParameters
Returns
Type Parameters
TException
RateLimit(Action<RateLimitOptions>)
Adds a configured rate limit. The handling clauses remain ambient for later strategies.
public Shield RateLimit(Action<RateLimitOptions> configure)Parameters
configureAction<RateLimitOptions>
Returns
RateLimit(int, TimeSpan)
Limits throughput. The handling clauses remain ambient for later strategies.
public Shield RateLimit(int permits, TimeSpan perWindow)Parameters
Returns
Retry(Action<RetryOptions>)
Adds a retry strategy configured via configure.
public Shield Retry(Action<RetryOptions> configure)Parameters
configureAction<RetryOptions>
Returns
Remarks
MaxRetries counts retries, not attempts:
MaxRetries = 3 makes up to 4 total attempts — the initial call plus 3 retries.
Retry(int)
Retries handled exceptions up to maxRetries times with the default exponential jittered backoff.
public Shield Retry(int maxRetries = 3)Parameters
maxRetriesintThe number of retries, not the number of attempts:
Retry(3)makes up to 4 total attempts — the initial call plus 3 retries.
Returns
Retry(int, Backoff)
Retries handled exceptions up to maxRetries times with the given backoff.
public Shield Retry(int maxRetries, Backoff backoff)Parameters
maxRetriesintThe number of retries, not the number of attempts:
Retry(3)makes up to 4 total attempts — the initial call plus 3 retries.backoffBackoffThe delay computation applied between attempts.
Returns
RetryForever()
Retries handled exceptions indefinitely with the default exponential jittered backoff.
public Shield RetryForever()Returns
RetryForever(Backoff)
Retries handled exceptions indefinitely with the given backoff.
public Shield RetryForever(Backoff backoff)Parameters
backoffBackoffThe delay computation applied between attempts.
Returns
Timeout(Action<TimeoutOptions>)
Adds a configured timeout. The handling clause remains ambient for later strategies.
public Shield Timeout(Action<TimeoutOptions> configure)Parameters
configureAction<TimeoutOptions>
Returns
Timeout(TimeSpan)
Cancels executions that exceed timeout. The handling clauses remain ambient for later strategies.
public Shield Timeout(TimeSpan timeout)Parameters
timeoutTimeSpan
Returns
Use(Strategy)
Appends a custom strategy. The accumulated handling clause remains ambient for later strategies.
public Shield Use(Strategy strategy)Parameters
strategyStrategy
Returns
Use(Func<HandlingClause, Strategy>)
Creates and appends a custom strategy using the accumulated handling clause.
public Shield Use(Func<HandlingClause, Strategy> factory)Parameters
factoryFunc<HandlingClause, Strategy>