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.

This guide walks you from a fresh .NET project to a fully wired chaos-engineering setup using Simmy. Each step builds on the last, so by the end you will have a synchronous fault-injection policy, a PolicyWrap that combines Simmy with standard Polly resilience policies, and an async latency-injection example ready to adapt for your own services.
1

Install the NuGet package

Add the Polly.Contrib.Simmy package to your project. Simmy targets .NET Standard 1.1, 2.0, and 2.1, so it works with any modern .NET runtime.
dotnet add package Polly.Contrib.Simmy
Once the package is installed, add the required namespaces at the top of your file:
using System.Net.Sockets;
using Polly;
using Polly.Contrib.Simmy;
2

Create a chaos policy that injects an exception

Use the MonkeyPolicy.InjectException fluent builder to define what fault to throw, how often to throw it, and whether the policy is active. The example below creates a SocketException and injects it on roughly 5 % of executions.
// Causes the policy to throw SocketException with a probability of 5% if enabled
var fault = new SocketException(errorCode: 10013);
var chaosPolicy = MonkeyPolicy.InjectException(with =>
    with.Fault(fault)
        .InjectionRate(0.05)
        .Enabled()
    );
InjectionRate accepts any value between 0 and 1. Use small values like 0.05 during early testing to keep the blast radius narrow, and increase the rate only as you gain confidence in your resilience setup.
3

Execute code through the chaos policy

A Simmy policy is executed exactly like any other Polly policy. Pass a delegate to Execute and the policy decides — based on the injection rate — whether to run it normally or throw the configured fault.
// Executes through the chaos policy directly
chaosPolicy.Execute(() => someMethod());

// Executes through the chaos policy using a Polly Context
chaosPolicy.Execute((ctx) => someMethod(), context);
When the policy triggers, it throws the configured SocketException before someMethod() is ever called. Your surrounding try/catch or outer Polly policies receive the exception exactly as they would if the real network had failed.
4

Wrap chaos inside a Polly PolicyWrap

Simmy policies are designed to sit innermost in a PolicyWrap. In that position they subvert the outbound call at the last moment, while the outer Polly policies (fallback, timeout, retry, etc.) still observe and react to whatever Simmy injects. This lets you validate that your existing resilience configuration actually handles the failures it is supposed to handle.
// Wrap the chaos policy inside other Polly resilience policies
var policyWrap = Policy
    .Wrap(fallbackPolicy, timeoutPolicy, chaosLatencyPolicy);
policyWrap.Execute(() => someMethod());
The outermost policy in a PolicyWrap is the first to handle any exception or result. Placing Simmy innermost ensures that the fault it injects travels outward through every resilience layer — giving you an end-to-end resilience test rather than a test of Simmy alone.
5

Use the async API with latency injection

All four chaos policy types have async counterparts. The example below creates an async latency policy that adds a five-second delay to 10 % of calls, then integrates it into an async PolicyWrap with a fallback and a timeout.
var chaosLatencyPolicy = MonkeyPolicy.InjectLatencyAsync(with =>
    with.Latency(TimeSpan.FromSeconds(5))
        .InjectionRate(0.1)
        .Enabled()
    );

var policyWrap = Policy
    .WrapAsync(fallbackPolicy, timeoutPolicy, chaosLatencyPolicy);

var result = await policyWrap.ExecuteAsync(
    token => service.GetFoo(parametersBar, token),
    myCancellationToken);
Because chaosLatencyPolicy is the innermost policy, the five-second latency it injects is visible to the outer timeoutPolicy. If your timeout threshold is, say, two seconds, the timeout will fire — exactly as it would in production when a real slow dependency causes the same delay. This is the value of testing your full resilience stack together.

​
What’s next

Now that you have a working chaos policy, explore the individual policy pages to see the full range of configuration options — including context-driven injection rates, delegate-based fault factories, and dynamic EnabledWhen callbacks that let you tie chaos to external configuration at runtime.

Inject Exception

Full reference for MonkeyPolicy.InjectException, including delegate-based fault factories.

Inject Result

Stub return values such as HTTP error responses without throwing an exception.

Inject Latency

Configure variable delays and validate your timeout thresholds under realistic conditions.

Inject Behaviour

Execute arbitrary pre-call actions to simulate infrastructure-level chaos events.

Build docs developers (and LLMs) love

Get started for freeTalk to us