125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# EonaCat.SmartRetry
|
|
|
|
[](https://www.nuget.org/packages/EonaCat.SmartRetry)
|
|
|
|
`EonaCat.SmartRetry` is a powerful and flexible .NET library for building resilient applications.
|
|
|
|
It provides **retry policies**, **circuit breakers**, **fallbacks**, **jittered backoff**, **async/sync support**, and more
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- Retry on **exceptions** or **result conditions**
|
|
- Configurable **retry count** and **max retry duration**
|
|
- **Exponential**, **linear**, or **custom backoff** strategies
|
|
- **Jitter** support to prevent thundering herd
|
|
- **Circuit breaker** with open, half-open, and closed states
|
|
- **Sync and async fallback actions**
|
|
- Retry **with cancellation tokens**
|
|
- Logging and async callbacks for retries and circuit breaker events
|
|
- Thread-safe for **multi-threaded operations**
|
|
- Named policies for reusable resilience configurations
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Install via NuGet:
|
|
|
|
```bash
|
|
dotnet add package EonaCat.SmartRetry
|
|
```
|
|
|
|
Or via Package Manager:
|
|
```csharp
|
|
Install-Package EonaCat.SmartRetry
|
|
```
|
|
|
|
# Usage Examples
|
|
## Basic Retry with Fallback
|
|
|
|
```csharp
|
|
using EonaCat.SmartRetry;
|
|
|
|
var policy = SmartRetryPolicy.Policy()
|
|
.Handle<TimeoutException>()
|
|
.Retry(3)
|
|
.WithExponentialBackoff(1, 2)
|
|
.WithFallbackAsync(async () =>
|
|
{
|
|
Console.WriteLine("Executing fallback...");
|
|
await Task.Delay(50);
|
|
|
|
// fallback value
|
|
return 42;
|
|
});
|
|
|
|
int result = await policy.ExecuteAsync<int>(async () =>
|
|
{
|
|
Console.WriteLine("Attempting operation...");
|
|
await Task.Delay(50);
|
|
throw new TimeoutException("Simulated failure");
|
|
});
|
|
|
|
// Outputs: 42
|
|
Console.WriteLine($"Result: {result}");
|
|
```
|
|
|
|
|
|
## Retry with Circuit Breaker, Jitter, and Logging
|
|
|
|
```csharp
|
|
var policy = SmartRetryPolicy.Policy()
|
|
.Handle<TimeoutException>()
|
|
.Retry(5)
|
|
.WithExponentialBackoff(1, 2)
|
|
.WithJitter(0.2)
|
|
.WithCircuitBreaker(failureThreshold: 3, openDuration: TimeSpan.FromSeconds(10))
|
|
.WithFallbackAsync(async () =>
|
|
{
|
|
Console.WriteLine("Executing fallback...");
|
|
await Task.Delay(50);
|
|
return -1;
|
|
})
|
|
.OnRetry((attempt, ex) => Console.WriteLine($"Retry {attempt}: {ex.Message}"))
|
|
.OnCircuitOpen(() => Console.WriteLine("Circuit breaker opened"))
|
|
.OnCircuitClose(() => Console.WriteLine("Circuit breaker closed"));
|
|
|
|
int result = await policy.ExecuteAsync<int>(async (ct) =>
|
|
{
|
|
Console.WriteLine("Attempting operation...");
|
|
await Task.Delay(50, ct);
|
|
throw new TimeoutException("Simulated failure");
|
|
});
|
|
|
|
Console.WriteLine($"Result: {result}");
|
|
|
|
```
|
|
|
|
## Retry Based on Result Condition
|
|
```csharp
|
|
var policy = SmartRetryPolicy.Policy()
|
|
.RetryIf<int>(value => value < 0) // retry if result is negative
|
|
.Retry(3)
|
|
.WithLinearBackoff(0.5)
|
|
.WithFallback(() => 0);
|
|
|
|
int result = policy.Execute(() =>
|
|
{
|
|
Console.WriteLine("Returning -1 to trigger retry...");
|
|
return -1;
|
|
});
|
|
|
|
// Outputs: 0 (fallback)
|
|
Console.WriteLine($"Result: {result}");
|
|
|
|
```
|
|
|
|
# Advanced Features
|
|
|
|
* Max Retry Duration: Stop retrying after a total duration.
|
|
* CancellationToken Support: Cancel retry loops gracefully.
|
|
* Custom Backoff Functions: Provide your own delay logic.
|
|
* Async Logging Hooks: Integrate with metrics or monitoring systems.
|
|
* Named Policies: Standardize retry/circuit-breaker behavior across your app. |