Class ShieldBuilder<TResult>

Namespace

Kevlar

Assembly

Kevlar.dll

An immutable exception and result handling clause under construction for a Shield<TResult> chain. Obtained via the When/WhenResult methods on Shield<TResult> and finished by adding a strategy. The clause becomes the shield's ambient handling for the strategy added here and reactive strategies chained afterwards.

public sealed class ShieldBuilder<TResult>

Type Parameters

TResult

Inheritance

object

ShieldBuilder<TResult>

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Start a clause with When… on a shield, then continue it with Or… on this builder: Shield.For<T>().When<A>().OrResult(r => …).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 or HandlesResult on its options (RetryOptions<TResult>, CircuitBreakerOptions<TResult>, HedgeOptions<TResult>, FallbackOptions<TResult>) makes that strategy ignore the clause and handle only what its own predicates select. Every other strategy in the chain keeps using the ambient clause.

Methods

CircuitBreaker(Action<CircuitBreakerOptions<TResult>>)

Adds a circuit breaker strategy configured via configure.

public Shield<TResult> CircuitBreaker(Action<CircuitBreakerOptions<TResult>> configure)

Parameters

configure Action<CircuitBreakerOptions<TResult>>

Returns

Shield<TResult>

CircuitBreaker(int, TimeSpan)

Breaks the circuit for breakDuration after consecutiveFailures consecutive handled outcomes.

public Shield<TResult> CircuitBreaker(int consecutiveFailures, TimeSpan breakDuration)

Parameters

consecutiveFailures int

breakDuration TimeSpan

Returns

Shield<TResult>

ConcurrencyLimit(Action<ConcurrencyLimitOptions>)

Adds a configured concurrency limit. The handling clauses remain ambient for later strategies.

public Shield<TResult> ConcurrencyLimit(Action<ConcurrencyLimitOptions> configure)

Parameters

configure Action<ConcurrencyLimitOptions>

Returns

Shield<TResult>

ConcurrencyLimit(int, int)

Caps concurrency. The handling clauses remain ambient for later strategies.

public Shield<TResult> ConcurrencyLimit(int maxConcurrency, int queueLimit = 0)

Parameters

maxConcurrency int

queueLimit int

Returns

Shield<TResult>

Fallback(Func<Outcome<TResult>, CancellationToken, ValueTask<TResult>>)

Replaces handled outcomes with the result of fallback, which receives the handled outcome.

public Shield<TResult> Fallback(Func<Outcome<TResult>, CancellationToken, ValueTask<TResult>> fallback)

Parameters

fallback Func<Outcome<TResult>, CancellationToken, ValueTask<TResult>>

Returns

Shield<TResult>

Fallback(Func<Outcome<TResult>, CancellationToken, ValueTask<TResult>>, Action<FallbackOptions<TResult>>)

Replaces handled outcomes with the result of fallback, which receives the handled outcome, and configures notifications.

public Shield<TResult> Fallback(Func<Outcome<TResult>, CancellationToken, ValueTask<TResult>> fallback, Action<FallbackOptions<TResult>> configure)

Parameters

fallback Func<Outcome<TResult>, CancellationToken, ValueTask<TResult>>

configure Action<FallbackOptions<TResult>>

Returns

Shield<TResult>

Fallback(Func<CancellationToken, ValueTask<TResult>>)

Replaces handled outcomes with the result of fallback.

public Shield<TResult> Fallback(Func<CancellationToken, ValueTask<TResult>> fallback)

Parameters

fallback Func<CancellationToken, ValueTask<TResult>>

Returns

Shield<TResult>

Fallback(Func<CancellationToken, ValueTask<TResult>>, Action<FallbackOptions<TResult>>)

Replaces handled outcomes with the result of fallback and configures notifications.

public Shield<TResult> Fallback(Func<CancellationToken, ValueTask<TResult>> fallback, Action<FallbackOptions<TResult>> configure)

Parameters

fallback Func<CancellationToken, ValueTask<TResult>>

configure Action<FallbackOptions<TResult>>

Returns

Shield<TResult>

FallbackTo(TResult)

Replaces handled outcomes with fallbackValue.

public Shield<TResult> FallbackTo(TResult fallbackValue)

Parameters

fallbackValue TResult

Returns

Shield<TResult>

FallbackTo(TResult, Action<FallbackOptions<TResult>>)

Replaces handled outcomes with fallbackValue and configures notifications.

public Shield<TResult> FallbackTo(TResult fallbackValue, Action<FallbackOptions<TResult>> configure)

Parameters

fallbackValue TResult

configure Action<FallbackOptions<TResult>>

Returns

Shield<TResult>

Hedge(Action<HedgeOptions<TResult>>)

Adds a hedging strategy configured via configure.

public Shield<TResult> Hedge(Action<HedgeOptions<TResult>> configure)

Parameters

configure Action<HedgeOptions<TResult>>

Returns

Shield<TResult>

Hedge(int, TimeSpan)

Races concurrent attempts; a handled outcome launches the next attempt immediately.

public Shield<TResult> Hedge(int maxHedgedAttempts, TimeSpan delay)

Parameters

maxHedgedAttempts int

delay TimeSpan

Returns

Shield<TResult>

Or(Func<Exception, bool>)

Returns a new builder that also handles exceptions matching predicate, whatever their type.

public ShieldBuilder<TResult> Or(Func<Exception, bool> predicate)

Parameters

predicate Func<Exception, bool>

Returns

ShieldBuilder<TResult>

OrContext(Func<HandlingEvent<TResult>, bool>)

Returns a new builder that also handles outcomes selected using execution context.

public ShieldBuilder<TResult> OrContext(Func<HandlingEvent<TResult>, bool> predicate)

Parameters

predicate Func<HandlingEvent<TResult>, bool>

Returns

ShieldBuilder<TResult>

OrInner<TException>()

Returns a new builder that also handles exceptions containing an exception of type TException.

public ShieldBuilder<TResult> OrInner<TException>() where TException : Exception

Returns

ShieldBuilder<TResult>

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<TResult> OrInner<TException>(Func<TException, bool> predicate) where TException : Exception

Parameters

predicate Func<TException, bool>

Returns

ShieldBuilder<TResult>

Type Parameters

TException

Remarks

The outer exception, ordinary inner-exception chains, and every branch of an AggregateException are searched.

OrResult(Func<TResult, bool>)

Returns a new builder that also handles results matching predicate.

public ShieldBuilder<TResult> OrResult(Func<TResult, bool> predicate)

Parameters

predicate Func<TResult, bool>

Returns

ShieldBuilder<TResult>

OrResultContext(Func<HandlingEvent<TResult>, bool>)

Returns a new builder that also handles results selected using execution context.

public ShieldBuilder<TResult> OrResultContext(Func<HandlingEvent<TResult>, bool> predicate)

Parameters

predicate Func<HandlingEvent<TResult>, bool>

Returns

ShieldBuilder<TResult>

OrResultEquals(TResult)

Returns a new builder that also handles results equal to result.

public ShieldBuilder<TResult> OrResultEquals(TResult result)

Parameters

result TResult

Returns

ShieldBuilder<TResult>

OrResultIsDefault()

Returns a new builder that also handles results equal to default(TResult) — null for reference types.

public ShieldBuilder<TResult> OrResultIsDefault()

Returns

ShieldBuilder<TResult>

Remarks

For a reference type prefer OrResultIsNull<TResult>(ShieldBuilder<TResult>), which says what it matches. This overload stays for value types and generic code, where default(TResult) — 0, false — may or may not be a failure.

Or<TException>()

Returns a new builder that also handles exceptions of type TException.

public ShieldBuilder<TResult> Or<TException>() where TException : Exception

Returns

ShieldBuilder<TResult>

Type Parameters

TException

Or<TException>(Func<TException, bool>)

Returns a new builder that also handles exceptions of type TException matching predicate.

public ShieldBuilder<TResult> Or<TException>(Func<TException, bool> predicate) where TException : Exception

Parameters

predicate Func<TException, bool>

Returns

ShieldBuilder<TResult>

Type Parameters

TException

RateLimit(Action<RateLimitOptions>)

Adds a configured rate limit. The handling clauses remain ambient for later strategies.

public Shield<TResult> RateLimit(Action<RateLimitOptions> configure)

Parameters

configure Action<RateLimitOptions>

Returns

Shield<TResult>

RateLimit(int, TimeSpan)

Limits throughput. The handling clauses remain ambient for later strategies.

public Shield<TResult> RateLimit(int permits, TimeSpan perWindow)

Parameters

permits int

perWindow TimeSpan

Returns

Shield<TResult>

Retry(Action<RetryOptions<TResult>>)

Adds a retry strategy configured via configure.

public Shield<TResult> Retry(Action<RetryOptions<TResult>> configure)

Parameters

configure Action<RetryOptions<TResult>>

Returns

Shield<TResult>

Remarks

MaxRetries counts retries, not attempts: MaxRetries = 3 makes up to 4 total attempts — the initial call plus 3 retries.

Retry(int)

Retries handled outcomes up to maxRetries times with the default exponential jittered backoff.

public Shield<TResult> Retry(int maxRetries = 3)

Parameters

maxRetries int

The number of retries, not the number of attempts: Retry(3) makes up to 4 total attempts — the initial call plus 3 retries.

Returns

Shield<TResult>

Retry(int, Backoff)

Retries handled outcomes up to maxRetries times with the given backoff.

public Shield<TResult> Retry(int maxRetries, Backoff backoff)

Parameters

maxRetries int

The number of retries, not the number of attempts: Retry(3) makes up to 4 total attempts — the initial call plus 3 retries.

backoff Backoff

The delay computation applied between attempts.

Returns

Shield<TResult>

RetryForever()

Retries handled outcomes indefinitely with the default exponential jittered backoff.

public Shield<TResult> RetryForever()

Returns

Shield<TResult>

RetryForever(Backoff)

Retries handled outcomes indefinitely with the given backoff.

public Shield<TResult> RetryForever(Backoff backoff)

Parameters

backoff Backoff

The delay computation applied between attempts.

Returns

Shield<TResult>

Timeout(Action<TimeoutOptions>)

Adds a configured timeout. The handling clause remains ambient for later strategies.

public Shield<TResult> Timeout(Action<TimeoutOptions> configure)

Parameters

configure Action<TimeoutOptions>

Returns

Shield<TResult>

Timeout(TimeSpan)

Cancels executions that exceed timeout. The handling clauses remain ambient for later strategies.

public Shield<TResult> Timeout(TimeSpan timeout)

Parameters

timeout TimeSpan

Returns

Shield<TResult>

Use(Strategy)

Appends a custom strategy. The accumulated handling clause remains ambient for later strategies.

public Shield<TResult> Use(Strategy strategy)

Parameters

strategy Strategy

Returns

Shield<TResult>

Use(Func<HandlingClause, Strategy>)

Creates and appends a custom strategy using the accumulated handling clause.

public Shield<TResult> Use(Func<HandlingClause, Strategy> factory)

Parameters

factory Func<HandlingClause, Strategy>

Returns

Shield<TResult>