Class ShieldExtensions

Namespace

Kevlar

Assembly

Kevlar.dll

Fluent chaining for Shield. Each call returns a new immutable shield with the strategy appended; the earliest strategy in a chain is the outermost at execution time.

public static class ShieldExtensions

Inheritance

object

ShieldExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

CircuitBreaker(Shield, Action<CircuitBreakerOptions>)

Appends a circuit breaker strategy configured via configure.

public static Shield CircuitBreaker(this Shield shield, Action<CircuitBreakerOptions> configure)

Parameters

shield Shield

configure Action<CircuitBreakerOptions>

Returns

Shield

CircuitBreaker(Shield, int, TimeSpan)

Appends a circuit breaker that opens for breakDuration after consecutiveFailures consecutive handled exceptions.

public static Shield CircuitBreaker(this Shield shield, int consecutiveFailures, TimeSpan breakDuration)

Parameters

shield Shield

consecutiveFailures int

breakDuration TimeSpan

Returns

Shield

ConcurrencyLimit(Shield, Action<ConcurrencyLimitOptions>)

Appends a concurrency limit strategy configured via configure.

public static Shield ConcurrencyLimit(this Shield shield, Action<ConcurrencyLimitOptions> configure)

Parameters

shield Shield

configure Action<ConcurrencyLimitOptions>

Returns

Shield

ConcurrencyLimit(Shield, int, int)

Appends a concurrency limit capping concurrency at maxConcurrency with an optional wait queue.

public static Shield ConcurrencyLimit(this Shield shield, int maxConcurrency, int queueLimit = 0)

Parameters

shield Shield

maxConcurrency int

queueLimit int

Returns

Shield

Fallback(Shield, Func<Exception, CancellationToken, ValueTask>)

Runs fallback in place of handled failures, receiving the handled exception. Applies to void executions only; result-returning executions fail with a descriptive InvalidOperationException. Use Shield.For<T>().FallbackTo(…) for constant values or its typed Fallback(…) overloads for factories.

public static Shield Fallback(this Shield shield, Func<Exception, CancellationToken, ValueTask> fallback)

Parameters

shield Shield

fallback Func<Exception, CancellationToken, ValueTask>

Returns

Shield

Fallback(Shield, Func<Exception, CancellationToken, ValueTask>, Action<FallbackOptions>)

Runs fallback in place of handled failures and configures notifications. Applies to void executions only.

public static Shield Fallback(this Shield shield, Func<Exception, CancellationToken, ValueTask> fallback, Action<FallbackOptions> configure)

Parameters

shield Shield

fallback Func<Exception, CancellationToken, ValueTask>

configure Action<FallbackOptions>

Returns

Shield

Remarks

Runs and awaits OnFallback before recovery. Notification failures are reported and recovery continues.

Fallback(Shield, Func<CancellationToken, ValueTask>)

Runs fallback in place of handled failures. Applies to void executions only; result-returning executions fail with a descriptive InvalidOperationException. Use Shield.For<T>().FallbackTo(…) for constant values or its typed Fallback(…) overloads for factories.

public static Shield Fallback(this Shield shield, Func<CancellationToken, ValueTask> fallback)

Parameters

shield Shield

fallback Func<CancellationToken, ValueTask>

Returns

Shield

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

Runs fallback in place of handled failures and configures notifications. Applies to void executions only.

public static Shield Fallback(this Shield shield, Func<CancellationToken, ValueTask> fallback, Action<FallbackOptions> configure)

Parameters

shield Shield

fallback Func<CancellationToken, ValueTask>

configure Action<FallbackOptions>

Returns

Shield

Remarks

Runs and awaits OnFallback before recovery. Notification failures are reported and recovery continues.

For<TResult>(Shield)

Lifts this shield into a result-aware Shield<TResult> so result-handling clauses can be chained. An ambient exception-handling clause carries over and stays ambient for strategies chained on the result-aware shield.

public static Shield<TResult> For<TResult>(this Shield shield)

Parameters

shield Shield

Returns

Shield<TResult>

Type Parameters

TResult

Hedge(Shield, Action<HedgeOptions>)

Appends a hedging strategy configured via configure.

public static Shield Hedge(this Shield shield, Action<HedgeOptions> configure)

Parameters

shield Shield

configure Action<HedgeOptions>

Returns

Shield

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(Shield, int, TimeSpan)

Appends hedging: up to maxHedgedAttempts additional attempts staggered by delay.

public static Shield Hedge(this Shield shield, int maxHedgedAttempts, TimeSpan delay)

Parameters

shield Shield

The shield to append hedging to.

maxHedgedAttempts int

Maximum additional attempts after the primary attempt.

delay TimeSpan

The delay between attempts. Zero launches attempts in parallel; any negative value launches another attempt only after a handled failure.

Returns

Shield

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.

RateLimit(Shield, Action<RateLimitOptions>)

Appends a rate limit strategy configured via configure.

public static Shield RateLimit(this Shield shield, Action<RateLimitOptions> configure)

Parameters

shield Shield

configure Action<RateLimitOptions>

Returns

Shield

RateLimit(Shield, int, TimeSpan)

Appends a token-bucket rate limit of permits executions per perWindow.

public static Shield RateLimit(this Shield shield, int permits, TimeSpan perWindow)

Parameters

shield Shield

permits int

perWindow TimeSpan

Returns

Shield

Retry(Shield, Action<RetryOptions>)

Appends a retry strategy configured via configure.

public static Shield Retry(this Shield shield, Action<RetryOptions> configure)

Parameters

shield Shield

configure Action<RetryOptions>

Returns

Shield

Remarks

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

Retry(Shield, int)

Appends a retry of handled exceptions, up to maxRetries times, with Default: exponential from 250 milliseconds with factor 2, equal jitter, and a 30-second cap.

public static Shield Retry(this Shield shield, int maxRetries = 3)

Parameters

shield Shield

The shield to append the retry to.

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

Retry(Shield, int, Backoff)

Appends a retry of handled exceptions, up to maxRetries times, with the given backoff.

public static Shield Retry(this Shield shield, int maxRetries, Backoff backoff)

Parameters

shield Shield

The shield to append the retry to.

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

RetryForever(Shield)

Appends a retry that never gives up, with Default: exponential from 250 milliseconds with factor 2, equal jitter, and a 30-second cap.

public static Shield RetryForever(this Shield shield)

Parameters

shield Shield

The shield to append the retry to.

Returns

Shield

RetryForever(Shield, Backoff)

Appends a retry that never gives up, with the given backoff.

public static Shield RetryForever(this Shield shield, Backoff backoff)

Parameters

shield Shield

The shield to append the retry to.

backoff Backoff

The delay computation applied between attempts.

Returns

Shield

Timeout(Shield, Action<TimeoutOptions>)

Appends a timeout strategy configured via configure.

public static Shield Timeout(this Shield shield, Action<TimeoutOptions> configure)

Parameters

shield Shield

configure Action<TimeoutOptions>

Returns

Shield

Timeout(Shield, TimeSpan)

Appends a timeout, surfacing TimeoutExceededException when exceeded.

public static Shield Timeout(this Shield shield, TimeSpan timeout)

Parameters

shield Shield

timeout TimeSpan

Returns

Shield

Use(Shield, Strategy)

Appends a custom Strategy implementation to the pipeline.

public static Shield Use(this Shield shield, Strategy strategy)

Parameters

shield Shield

strategy Strategy

Returns

Shield

Use(Shield, Func<HandlingClause, Strategy>)

Appends a custom strategy created from the active handling clause. The factory runs once; reactive custom strategies should retain and consult the supplied clause.

public static Shield Use(this Shield shield, Func<HandlingClause, Strategy> factory)

Parameters

shield Shield

factory Func<HandlingClause, Strategy>

Returns

Shield

When(Shield, Func<Exception, bool>)

Starts a handling clause for exceptions matching predicate. Use WithDefaultHandling(Shield) to return to default handling.

public static ShieldBuilder When(this Shield shield, Func<Exception, bool> predicate)

Parameters

shield Shield

predicate Func<Exception, bool>

Returns

ShieldBuilder

WhenContext(Shield, Func<HandlingEvent, bool>)

Starts a handling clause using the active execution and strategy context.

public static ShieldBuilder WhenContext(this Shield shield, Func<HandlingEvent, bool> predicate)

Parameters

shield Shield

predicate Func<HandlingEvent, bool>

Returns

ShieldBuilder

WhenInner<TException>(Shield)

Starts a handling clause for exceptions containing an exception of type TException. Use WithDefaultHandling(Shield) to return to default handling.

public static ShieldBuilder WhenInner<TException>(this Shield shield) where TException : Exception

Parameters

shield Shield

Returns

ShieldBuilder

Type Parameters

TException

Remarks

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

WhenInner<TException>(Shield, Func<TException, bool>)

Starts a handling clause for exceptions containing an exception of type TException matching predicate. Use WithDefaultHandling(Shield) to return to default handling.

public static ShieldBuilder WhenInner<TException>(this Shield shield, Func<TException, bool> predicate) where TException : Exception

Parameters

shield Shield

predicate Func<TException, bool>

Returns

ShieldBuilder

Type Parameters

TException

Remarks

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

When<TException>(Shield)

Starts a handling clause: subsequent reactive strategies act on exceptions of type TException. Use WithDefaultHandling(Shield) to return to default handling.

public static ShieldBuilder When<TException>(this Shield shield) where TException : Exception

Parameters

shield Shield

Returns

ShieldBuilder

Type Parameters

TException

When<TException>(Shield, Func<TException, bool>)

Starts a handling clause for exceptions of type TException matching predicate. Use WithDefaultHandling(Shield) to return to default handling.

public static ShieldBuilder When<TException>(this Shield shield, Func<TException, bool> predicate) where TException : Exception

Parameters

shield Shield

predicate Func<TException, bool>

Returns

ShieldBuilder

Type Parameters

TException

WithDefaultHandling(Shield)

Resets the ambient handling clause. Subsequent reactive strategies use the default handling defined by Default.

public static Shield WithDefaultHandling(this Shield shield)

Parameters

shield Shield

Returns

Shield

WithName(Shield, string)

Returns a copy of this shield with a diagnostic name (surfaced as ShieldName).

public static Shield WithName(this Shield shield, string name)

Parameters

shield Shield

name string

Returns

Shield

WithTimeProvider(Shield, TimeProvider)

Returns a copy of this shield using the given TimeProvider for delays, timeouts and time windows.

public static Shield WithTimeProvider(this Shield shield, TimeProvider timeProvider)

Parameters

shield Shield

timeProvider TimeProvider

Returns

Shield

Wrap(Shield, Shield)

Wraps inner inside outer: the outer shield's strategies run first. The first non-null name and time provider win. Composition seals handling clauses, so reactive strategies appended afterwards use default handling unless a new clause is declared.

public static Shield Wrap(this Shield outer, Shield inner)

Parameters

outer Shield

inner Shield

Returns

Shield

Wrap<TResult>(Shield, Shield<TResult>)

Wraps a result-aware inner shield inside outer, producing a result-aware shield. The first non-null name and time provider win. Composition seals handling clauses, so reactive strategies appended afterwards use default handling unless a new clause is declared.

public static Shield<TResult> Wrap<TResult>(this Shield outer, Shield<TResult> inner)

Parameters

outer Shield

inner Shield<TResult>

Returns

Shield<TResult>

Type Parameters

TResult