A minimalist, dependency-free retry and timeout utility for C#. Provides type-safe retry policies with configurable delays, exponential backoff, timeout support, and exception filtering.
✅ Timeout Support - Built-in timeout with cancellation token integration
✅ Exception Filtering - Retry only specific exception types
✅ Async-First - Full support for async/await patterns
✅ Observability - OnRetry callbacks, telemetry support
✅ Jitter - Random variation to prevent thundering herd
✅ Well-Documented - Comprehensive XML documentation
Installation
dotnet add package Fox.RetryKit
Quick Start
Basic Retry
using Fox.RetryKit;
// Retry up to 3 times
var policy = RetryPolicy.Retry(3);
policy.Execute(() =>
{
CallUnstableService();
});
Retry with Delay
// Retry 3 times with 500ms delay
var policy = RetryPolicy.Retry(3, TimeSpan.FromMilliseconds(500));
await policy.ExecuteAsync(async () =>
{
await CallUnstableApiAsync();
});
Exponential Backoff
// Retry 5 times with exponential backoff (100ms, 200ms, 400ms, 800ms, 1600ms)
var policy = RetryPolicy.ExponentialBackoff(5, TimeSpan.FromMilliseconds(100));
var result = await policy.ExecuteAsync(async () =>
{
return await FetchDataAsync();
});
Combined Policy
// Combine retry, delay, timeout, and exception filtering
var policy = RetryPolicy.Retry(3, TimeSpan.FromMilliseconds(500))
.Handle<HttpRequestException>()
.WithTimeout(TimeSpan.FromSeconds(10));
var data = await policy.ExecuteAsync(async () =>
{
return await FetchFromUnstableServiceAsync();
});
Extended Features
OnRetry Callback
var policy = RetryPolicy.Retry(3, TimeSpan.FromMilliseconds(100))
.OnRetry((exception, attempt, delay) =>
{
Console.WriteLine($"Retry {attempt} after {delay.TotalMilliseconds}ms: {exception.Message}");
});
Jitter (Prevent Thundering Herd)
var policy = RetryPolicy.Retry(5, TimeSpan.FromMilliseconds(200))
.WithJitter(); // Adds ±25% random variation
MaxDelay Cap
var policy = RetryPolicy.ExponentialBackoff(10, TimeSpan.FromMilliseconds(100))
.WithMaxDelay(TimeSpan.FromSeconds(5)); // Cap at 5 seconds
WaitAndRetry (Custom Delays)
var delays = new[]
{
TimeSpan.FromMilliseconds(100),
TimeSpan.FromMilliseconds(250),
TimeSpan.FromMilliseconds(500),
TimeSpan.FromSeconds(1)
};
var policy = RetryPolicy.WaitAndRetry(delays);
Fallback
var policy = RetryPolicy.Retry(3, TimeSpan.FromMilliseconds(100));
// Static fallback value
var result = policy.Fallback(() => GetRemoteData(), "default-value");
// Dynamic fallback provider
var result = policy.Fallback(() => GetPrimaryData(), () => GetCachedData());
RetryIf (Conditional Retry)
var policy = RetryPolicy.Retry(5, TimeSpan.FromMilliseconds(100))
.RetryIf<HttpResponseMessage>(response => !response.IsSuccessStatusCode);
RetryResult (Telemetry)
var result = await policy.ExecuteWithResultAsync(async () => await FetchDataAsync());
Console.WriteLine($"Success: {result.Success}");
Console.WriteLine($"Attempts: {result.Attempts}");
Console.WriteLine($"Duration: {result.TotalDuration}");
Real-World Examples
HTTP API Calls
var httpPolicy = RetryPolicy.Retry(5, TimeSpan.FromMilliseconds(500))
.Handle<HttpRequestException>()
.WithTimeout(TimeSpan.FromSeconds(30));
var response = await httpPolicy.ExecuteAsync(async () =>
{
using var client = new HttpClient();
return await client.GetStringAsync("https://api.example.com/data");
});
Database Operations
var dbPolicy = RetryPolicy.ExponentialBackoff(3, TimeSpan.FromSeconds(1))
.Handle<SqlException>()
.Handle<TimeoutException>();
await dbPolicy.ExecuteAsync(async () =>
{
await using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
});
File I/O
var filePolicy = RetryPolicy.Retry(3, TimeSpan.FromMilliseconds(100))
.Handle<IOException>();
var content = filePolicy.Execute(() => File.ReadAllText("config.json"));