> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/App-vNext/Polly/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get up and running with Polly in minutes
This quickstart guide will help you create your first resilience pipeline with Polly and execute code with automatic retry and timeout handling.
## Prerequisites
* .NET 6.0 or later
* Basic understanding of C# and async/await
## Step 1: Install Polly.Core
Install the Polly.Core package using the .NET CLI:
```bash theme={null}
dotnet add package Polly.Core
```
The package should now appear in your project file:
```xml theme={null}
```
## Step 2: Create your first resilience pipeline
Create a resilience pipeline that combines retry and timeout strategies:
```csharp theme={null}
using Polly;
// Create an instance of builder that exposes various extensions for adding resilience strategies
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions()) // Add retry using the default options
.AddTimeout(TimeSpan.FromSeconds(10)) // Add 10 seconds timeout
.Build(); // Builds the resilience pipeline
// Execute the pipeline asynchronously
await pipeline.ExecuteAsync(static async token =>
{
// Your custom logic goes here
var response = await httpClient.GetAsync("https://api.example.com/data", token);
return response;
}, cancellationToken);
```
The pipeline executes strategies in the order they are added. In this example, timeout wraps retry, which wraps your callback.
## Step 3: Configure advanced retry behavior
Customize the retry strategy with exponential backoff and jitter:
```csharp theme={null}
var pipeline = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions
{
MaxRetryAttempts = 3,
Delay = TimeSpan.FromSeconds(1),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true,
OnRetry = args =>
{
Console.WriteLine($"Retry attempt {args.AttemptNumber}");
return ValueTask.CompletedTask;
}
})
.AddTimeout(TimeSpan.FromSeconds(10))
.Build();
```
## Step 4: Use dependency injection (optional)
For ASP.NET Core and other DI-enabled applications, install Polly.Extensions:
```bash .NET CLI theme={null}
dotnet add package Polly.Extensions
```
```bash Package Manager theme={null}
Install-Package Polly.Extensions
```
Then register your resilience pipeline:
```csharp theme={null}
using Microsoft.Extensions.DependencyInjection;
using Polly;
var services = new ServiceCollection();
// Define a resilience pipeline with the name "my-pipeline"
services.AddResiliencePipeline("my-pipeline", builder =>
{
builder
.AddRetry(new RetryStrategyOptions())
.AddTimeout(TimeSpan.FromSeconds(10));
});
// Build the service provider
var serviceProvider = services.BuildServiceProvider();
// Retrieve a ResiliencePipelineProvider that dynamically creates and caches the resilience pipelines
var pipelineProvider = serviceProvider.GetRequiredService>();
// Retrieve your resilience pipeline using the name it was registered with
ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");
// Alternatively, you can use keyed services to retrieve the resilience pipeline
pipeline = serviceProvider.GetRequiredKeyedService("my-pipeline");
// Execute the pipeline
await pipeline.ExecuteAsync(static async token =>
{
// Your custom logic goes here
});
```
## Complete example: HTTP client with resilience
Here's a complete example showing how to use Polly with HttpClient in an ASP.NET Core application:
```csharp theme={null}
using Microsoft.Extensions.DependencyInjection;
using Polly;
var builder = WebApplication.CreateBuilder(args);
// Register HttpClient with Polly resilience pipeline
builder.Services.AddHttpClient("ResilientClient")
.AddResilienceHandler("my-pipeline", builder =>
{
builder
.AddRetry(new RetryStrategyOptions
{
MaxRetryAttempts = 3,
Delay = TimeSpan.FromSeconds(1),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true
})
.AddCircuitBreaker(new CircuitBreakerStrategyOptions
{
FailureRatio = 0.5,
MinimumThroughput = 10,
SamplingDuration = TimeSpan.FromSeconds(30),
BreakDuration = TimeSpan.FromSeconds(30)
})
.AddTimeout(TimeSpan.FromSeconds(10));
});
var app = builder.Build();
// Use the HttpClient in a controller or service
app.MapGet("/fetch-data", async (IHttpClientFactory factory) =>
{
var client = factory.CreateClient("ResilientClient");
var response = await client.GetAsync("https://api.example.com/data");
var content = await response.Content.ReadAsStringAsync();
return Results.Ok(content);
});
app.Run();
```
## What's next?
Learn about resilience pipelines and strategies in depth
Explore all available resilience strategies
Advanced DI patterns and configuration
Monitor your resilience pipelines
## Common patterns
### Generic pipelines for typed results
Use `ResiliencePipeline` when you need to handle results:
```csharp theme={null}
var pipeline = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions
{
ShouldHandle = new PredicateBuilder()
.Handle()
.HandleResult(r => !r.IsSuccessStatusCode)
})
.Build();
HttpResponseMessage response = await pipeline.ExecuteAsync(
async token => await httpClient.GetAsync("https://api.example.com", token),
cancellationToken);
```
### Multiple independent pipelines
Create different pipelines for different scenarios:
```csharp theme={null}
// Fast-failing pipeline for user-facing operations
var userPipeline = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 2 })
.AddTimeout(TimeSpan.FromSeconds(3))
.Build();
// Resilient pipeline for background operations
var backgroundPipeline = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 5 })
.AddTimeout(TimeSpan.FromSeconds(30))
.Build();
```
Pipeline instances are lightweight and can be reused across multiple executions. Create them once and store them for the lifetime of your application.