Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Polly-Contrib/Simmy/llms.txt

Use this file to discover all available pages before exploring further.

InjectOutcomeOptions<TResult> and InjectOutcomeAsyncOptions<TResult> are the configuration objects you pass to MonkeyPolicy.InjectException, MonkeyPolicy.InjectResult, and their async counterparts. Both types follow the same fluent builder pattern: you receive a fresh options instance inside the configureOptions callback, chain extension methods to configure the fault or result to inject along with the rate and enabled condition, and the factory validates the fully configured object before constructing the policy. The sync and async variants share the same design; the only difference is that async delegates return Task<T>.

​
Namespaces

using Polly.Contrib.Simmy.Outcomes; // options types
using Polly.Contrib.Simmy;          // base extension methods

​
InjectOutcomeOptions<TResult> (sync)

public class InjectOutcomeOptions<TResult> : InjectOptionsBase
Synchronous options object for outcome-injection policies. Inherits InjectionRate and Enabled delegates from InjectOptionsBase. The internal OutcomeInternal property stores the resolved outcome delegate and is set by the extension methods below.

​
InjectOutcomeAsyncOptions<TResult> (async)

public class InjectOutcomeAsyncOptions<TResult> : InjectOptionsAsyncBase
Asynchronous options object for outcome-injection policies. Inherits async InjectionRate and Enabled delegates (Task<double> / Task<bool>) from InjectOptionsAsyncBase. The internal Outcome property stores the async outcome delegate.

​
Fault extension methods (exception injection)

These methods are defined on InjectOutcomeOptionsExtensions and InjectOutcomeAsyncOptionsExtensions. They apply when TResult is Exception.

​
.Fault(Exception) — sync

Configures a specific exception instance to throw. 
public static InjectOutcomeOptions<Exception> Fault(
    this InjectOutcomeOptions<Exception> options,
    Exception fault)
​
options
InjectOutcomeOptions<Exception>
required
The options object being configured (supplied automatically by the fluent chain).
​
fault
Exception
required
The exception instance that the policy will throw on every triggered injection. The same object is reused across calls; create a new instance via the delegate overload if you need distinct instances.
MonkeyPolicy.InjectException(with =>
    with.Fault(new TimeoutException("chaos: downstream timed out"))
        .InjectionRate(0.05)
        .Enabled());

​
.Fault(Func<Context, CancellationToken, Exception>) — sync delegate

Configures a delegate that is called at injection-time to produce the exception, giving access to the current Polly Context and CancellationToken. 
public static InjectOutcomeOptions<Exception> Fault(
    this InjectOutcomeOptions<Exception> options,
    Func<Context, CancellationToken, Exception> fault)
​
options
InjectOutcomeOptions<Exception>
required
The options object being configured.
​
fault
Func<Context, CancellationToken, Exception>
required
A delegate invoked at injection-time. Receives the Polly execution context and a cancellation token; returns the exception to throw.
MonkeyPolicy.InjectException(with =>
    with.Fault((ctx, ct) =>
        {
            var op = ctx.OperationKey;
            return new InvalidOperationException($"chaos fault for operation '{op}'");
        })
        .InjectionRate(0.1)
        .Enabled());

​
.Fault(Exception) — async

Configures a specific exception instance for an async policy. 
public static InjectOutcomeAsyncOptions<Exception> Fault(
    this InjectOutcomeAsyncOptions<Exception> options,
    Exception fault)
​
options
InjectOutcomeAsyncOptions<Exception>
required
The async options object being configured.
​
fault
Exception
required
The exception instance to inject. Internally wrapped in Task.FromResult(fault).
MonkeyPolicy.InjectExceptionAsync(with =>
    with.Fault(new HttpRequestException("chaos: simulated network failure"))
        .InjectionRate(0.05)
        .Enabled());

​
.Fault(Func<Context, CancellationToken, Task<Exception>>) — async delegate

Configures an async delegate that produces the exception at injection-time. 
public static InjectOutcomeAsyncOptions<Exception> Fault(
    this InjectOutcomeAsyncOptions<Exception> options,
    Func<Context, CancellationToken, Task<Exception>> fault)
​
options
InjectOutcomeAsyncOptions<Exception>
required
The async options object being configured.
​
fault
Func<Context, CancellationToken, Task<Exception>>
required
An async delegate that returns a Task<Exception>. Receives the Polly Context and CancellationToken; useful when the exception type or message must be resolved asynchronously (for example, from a feature flag service).
MonkeyPolicy.InjectExceptionAsync(with =>
    with.Fault(async (ctx, ct) =>
        {
            var msg = await featureFlags.GetChaosMessageAsync(ct);
            return new Exception(msg);
        })
        .InjectionRate(0.1)
        .Enabled());

​
Result extension methods (result injection)

These methods apply when TResult is a non-exception result type.

​
.Result<TResult>(TResult) — sync

Configures a fixed result value to return in place of executing the wrapped delegate. 
public static InjectOutcomeOptions<TResult> Result<TResult>(
    this InjectOutcomeOptions<TResult> options,
    TResult result)
​
options
InjectOutcomeOptions<TResult>
required
The options object being configured.
​
result
TResult
required
The value that the policy returns on every triggered injection, bypassing the wrapped delegate entirely.
MonkeyPolicy.InjectResult<HttpResponseMessage>(with =>
    with.Result(new HttpResponseMessage(HttpStatusCode.ServiceUnavailable))
        .InjectionRate(0.1)
        .Enabled());

​
.Result<TResult>(Func<Context, CancellationToken, TResult>) — sync delegate

Configures a delegate that produces the result at injection-time. 
public static InjectOutcomeOptions<TResult> Result<TResult>(
    this InjectOutcomeOptions<TResult> options,
    Func<Context, CancellationToken, TResult> result)
​
options
InjectOutcomeOptions<TResult>
required
The options object being configured.
​
result
Func<Context, CancellationToken, TResult>
required
A delegate invoked at injection-time. Receives the Polly Context and a CancellationToken; returns the TResult value to inject.
MonkeyPolicy.InjectResult<int>(with =>
    with.Result((ctx, ct) => -1)
        .InjectionRate(0.2)
        .Enabled());

​
.Result<TResult>(TResult) — async

Configures a fixed result value for an async outcome policy. 
public static InjectOutcomeAsyncOptions<TResult> Result<TResult>(
    this InjectOutcomeAsyncOptions<TResult> options,
    TResult result)
​
options
InjectOutcomeAsyncOptions<TResult>
required
The async options object being configured.
​
result
TResult
required
The value to return. Internally wrapped in Task.FromResult(result).
MonkeyPolicy.InjectResultAsync<string>(with =>
    with.Result("chaos-injected-response")
        .InjectionRate(0.1)
        .Enabled());

​
.Result<TResult>(Func<Context, CancellationToken, Task<TResult>>) — async delegate

Configures an async delegate that produces the result at injection-time. 
public static InjectOutcomeAsyncOptions<TResult> Result<TResult>(
    this InjectOutcomeAsyncOptions<TResult> options,
    Func<Context, CancellationToken, Task<TResult>> result)
​
options
InjectOutcomeAsyncOptions<TResult>
required
The async options object being configured.
​
result
Func<Context, CancellationToken, Task<TResult>>
required
An async delegate returning Task<TResult>. The context and cancellation token allow the injected value to be resolved from an async source such as a configuration store.
MonkeyPolicy.InjectResultAsync<string>(with =>
    with.Result(async (ctx, ct) =>
        {
            return await configStore.GetFallbackValueAsync(ct);
        })
        .InjectionRate(0.1)
        .Enabled());

​
Inherited base options

Both InjectOutcomeOptions<TResult> and InjectOutcomeAsyncOptions<TResult> inherit activation and rate-control methods from their base classes. These must always be configured — the factory will throw ArgumentNullException if either is missing.

​
Sync base (InjectOptionsBaseExtensions)

​
.Enabled() — always on

public static InjectOptionsBase Enabled(this InjectOptionsBase options)
Marks the policy as unconditionally enabled. Equivalent to .Enabled(true).

​
.Enabled(bool)

public static InjectOptionsBase Enabled(this InjectOptionsBase options, bool enabled)
​
enabled
bool
required
Pass true to activate the policy, false to deactivate it entirely (no chaos is injected regardless of injection rate).

​
.EnabledWhen(Func<Context, CancellationToken, bool>)

public static InjectOptionsBase EnabledWhen(
    this InjectOptionsBase options,
    Func<Context, CancellationToken, bool> enabledWhen)
​
enabledWhen
Func<Context, CancellationToken, bool>
required
A delegate evaluated on every execution. Return true to allow chaos injection for that call; false to skip it. Useful for environment-flag checks or per-operation-key gating.
with.EnabledWhen((ctx, ct) =>
    Environment.GetEnvironmentVariable("CHAOS_ENABLED") == "true")

​
.InjectionRate(double)

public static InjectOptionsBase InjectionRate(this InjectOptionsBase options, double injectionRate)
​
injectionRate
double
required
A constant rate in the range [0, 1]. 0 means never inject; 1 means inject on every call. Values outside the range throw an ArgumentOutOfRangeException.

​
.InjectionRate(Func<Context, CancellationToken, double>)

public static InjectOptionsBase InjectionRate(
    this InjectOptionsBase options,
    Func<Context, CancellationToken, double> injectionRateProvider)
​
injectionRateProvider
Func<Context, CancellationToken, double>
required
A delegate evaluated on each execution to get a dynamic injection rate. Use this to vary chaos intensity at runtime, for example by reading from a feature flag or a shared configuration value.

​
Async base (InjectOptionsAsyncBaseExtensions)

The async base provides the same .Enabled(), .Enabled(bool), and .InjectionRate(double) overloads as the sync base. It additionally offers async-delegate overloads:

​
.EnabledWhen(Func<Context, CancellationToken, Task<bool>>)

public static InjectOptionsAsyncBase EnabledWhen(
    this InjectOptionsAsyncBase options,
    Func<Context, CancellationToken, Task<bool>> enabledWhen)
​
enabledWhen
Func<Context, CancellationToken, Task<bool>>
required
An async delegate that returns Task<bool>. Allows the enabled check to call async services such as a remote feature-flag API.

​
.InjectionRate(Func<Context, CancellationToken, Task<double>>)

public static InjectOptionsAsyncBase InjectionRate(
    this InjectOptionsAsyncBase options,
    Func<Context, CancellationToken, Task<double>> injectionRateProvider)
​
injectionRateProvider
Func<Context, CancellationToken, Task<double>>
required
An async delegate returning Task<double> in the range [0, 1]. Enables dynamically fetching the chaos rate from a remote configuration service.

​
Complete examples

​
Sync exception injection

using Polly.Contrib.Simmy;
using Polly.Contrib.Simmy.Outcomes;

// Inject a TimeoutException on ~5% of calls, always enabled
var faultPolicy = MonkeyPolicy.InjectException(with =>
    with.Fault(new TimeoutException("simulated timeout"))
        .InjectionRate(0.05)
        .Enabled());

// Wrap a real policy for a combined resilience + chaos strategy
var retryPolicy = Policy
    .Handle<TimeoutException>()
    .Retry(3);

var combined = Policy.Wrap(retryPolicy, faultPolicy);
combined.Execute(() => CallDownstreamService());

​
Async result injection with dynamic rate

using Polly.Contrib.Simmy;
using Polly.Contrib.Simmy.Outcomes;

var chaosPolicy = MonkeyPolicy.InjectResultAsync<HttpResponseMessage>(with =>
    with.Result(new HttpResponseMessage(HttpStatusCode.TooManyRequests))
        .InjectionRate(async (ctx, ct) =>
        {
            // Read live chaos rate from configuration store
            return await configStore.GetChaosRateAsync(ct);
        })
        .EnabledWhen(async (ctx, ct) =>
        {
            return await featureFlags.IsChaosEnabledAsync(ct);
        }));

var response = await chaosPolicy.ExecuteAsync(
    async ct => await httpClient.GetAsync("/api/resource", ct),
    CancellationToken.None);

Build docs developers (and LLMs) love

Get started for freeTalk to us