Skip to main content

​
V7 Compatibility

Polly v8 maintains full backward compatibility with v7 through the main Polly NuGet package. This allows you to upgrade to v8 and migrate your code gradually without breaking existing functionality.

​
Understanding the Package Structure

Polly v8 introduces a new package structure to support both the new v8 APIs and legacy v7 APIs:

​
Polly.Core Package

The Polly.Core package contains only the new v8 resilience pipeline APIs. This is the recommended package for new applications or after you have fully migrated from v7 to v8. Features:
  • New resilience pipeline API
  • Resilience strategies (retry, circuit breaker, timeout, etc.)
  • Built-in telemetry
  • Enhanced performance
  • No legacy v7 APIs

​
Polly Package

The Polly package includes everything from Polly.Core plus all the v7 policy APIs. This package is designed for migration scenarios. Features:
  • Everything from Polly.Core
  • Full v7 policy API (IAsyncPolicy, ISyncPolicy, etc.)
  • Interoperability between v7 and v8 APIs
  • Backward compatibility with existing v7 code
The v7 API is still available and fully supported even when using the v8 version by referencing the Polly package.

​
Migration Strategy

When migrating from v7 to v8, follow this recommended approach:

​
Step 1: Upgrade to Polly 8.x

Upgrade your NuGet package reference from Polly 7.x to Polly 8.x: 
<PackageReference Include="Polly" Version="8.0.0" />
Your existing v7 policies will continue to work without any code changes: 
// This v7 code continues to work with Polly 8.x
IAsyncPolicy retryPolicy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

await retryPolicy.ExecuteAsync(async () =>
{
    // Your code here
});

​
Step 2: Migrate Gradually

Migrate your v7 policies to v8 strategies one at a time. Test each migration thoroughly before moving to the next. 
IAsyncPolicy<HttpResponseMessage> policy = Policy
    .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
    .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(retryAttempt));

var response = await policy.ExecuteAsync(async () =>
{
    return await httpClient.GetAsync("https://api.example.com/data");
});

​
Step 3: Switch to Polly.Core

Once you have successfully migrated all your v7 policies to v8 strategies, switch from the Polly package to Polly.Core: 
<!-- Remove this -->
<PackageReference Include="Polly" Version="8.0.0" />

<!-- Add this -->
<PackageReference Include="Polly.Core" Version="8.0.0" />
Only switch to Polly.Core after you have removed all v7 API usage from your codebase. The Polly.Core package does not include the v7 APIs.

​
Interoperability Features

The Polly package provides extension methods that enable interoperability between v7 policies and v8 resilience pipelines.

​
Converting Resilience Pipelines to Policies

You can convert v8 resilience pipelines to v7 policies using the AsSyncPolicy() and AsAsyncPolicy() extension methods: 
// Create a v8 resilience pipeline
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddTimeout(TimeSpan.FromSeconds(10))
    .AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 3,
        Delay = TimeSpan.FromSeconds(1)
    })
    .Build();

// Convert to v7 policies
ISyncPolicy syncPolicy = pipeline.AsSyncPolicy();
IAsyncPolicy asyncPolicy = pipeline.AsAsyncPolicy();

// Use the v7 policy in existing code
await asyncPolicy.ExecuteAsync(async () =>
{
    // Your existing v7 code
});

​
Mixing v7 and v8 APIs

You can mix v7 policies and v8 resilience pipelines in the same application: 
// v8 resilience pipeline
ResiliencePipeline<HttpResponseMessage> retryPipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
    .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
    {
        ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
            .HandleResult(r => !r.IsSuccessStatusCode),
        MaxRetryAttempts = 3
    })
    .Build();

// v7 timeout policy
IAsyncPolicy<HttpResponseMessage> timeoutPolicy = Policy
    .TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(10));

// Convert v8 pipeline to v7 policy for wrapping
IAsyncPolicy<HttpResponseMessage> retryPolicy = retryPipeline.AsAsyncPolicy();

// Wrap them together using v7 API
IAsyncPolicy<HttpResponseMessage> combinedPolicy = Policy.WrapAsync(retryPolicy, timeoutPolicy);

var response = await combinedPolicy.ExecuteAsync(async () =>
{
    return await httpClient.GetAsync("https://api.example.com/data");
});

​
When to Use Which Package

​
Use Polly Package When:

  • You are migrating from v7 to v8
  • You have existing v7 policies in your codebase
  • You need interoperability between v7 and v8 APIs
  • You want to upgrade to v8 without breaking changes

​
Use Polly.Core Package When:

  • You are starting a new project
  • You have fully migrated all v7 policies to v8 strategies
  • You don’t need any v7 API compatibility
  • You want the smallest package footprint

​
Key Differences to Understand

While the Polly package maintains backward compatibility, it’s important to understand the key differences between v7 and v8:

​
API Philosophy

  • Static factory methods (Policy.Handle<>(), Policy.Timeout(), etc.)
  • Separate sync and async policies
  • Policy wrapping for composition
  • Direct context passing

​
Terminology

v7 Termv8 Term
PolicyStrategy
Policy WrapResilience Pipeline
IAsyncPolicy / ISyncPolicyResiliencePipeline
ContextResilienceContext
Policy RegistryResilience Pipeline Registry

​
Feature Comparison

Featurev7v8
Retry✅✅
Circuit Breaker✅✅ (Advanced only)
Timeout✅✅ (Optimistic only)
Bulkhead✅✅ (As Concurrency Limiter)
Rate Limiter✅✅ (Uses System.Threading.RateLimiting)
Fallback✅✅
Cache✅✅
Hedging❌✅
Built-in Telemetry❌✅
Chaos EngineeringLimited✅ (Polly.Testing)

​
Common Migration Scenarios

​
Scenario 1: Web API with Retry and Circuit Breaker

public class OrderService
{
    private readonly IAsyncPolicy<HttpResponseMessage> _policy;
    
    public OrderService()
    {
        var retry = Policy
            .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
            .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(retryAttempt));
            
        var circuitBreaker = Policy
            .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
            .CircuitBreakerAsync(5, TimeSpan.FromSeconds(30));
            
        _policy = Policy.WrapAsync(retry, circuitBreaker);
    }
    
    public async Task<Order> GetOrderAsync(string orderId)
    {
        var response = await _policy.ExecuteAsync(async () =>
        {
            return await httpClient.GetAsync($"/orders/{orderId}");
        });
        
        return await response.Content.ReadFromJsonAsync<Order>();
    }
}

​
Scenario 2: Using Dependency Injection

public void ConfigureServices(IServiceCollection services)
{
    var registry = new PolicyRegistry();
    
    var retryPolicy = Policy
        .Handle<HttpRequestException>()
        .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(retryAttempt));
        
    registry.Add("RetryPolicy", retryPolicy);
    
    services.AddSingleton<IReadOnlyPolicyRegistry<string>>(registry);
}

​
Benefits of Migrating to v8

While v7 compatibility is maintained, migrating to v8 provides several benefits:

​
Performance Improvements

  • Context pooling reduces allocations
  • Zero-allocation APIs for high-performance scenarios
  • Optimized execution paths for common scenarios

​
Enhanced Features

  • Built-in telemetry with OpenTelemetry support
  • Hedging strategy for parallel execution
  • Chaos engineering support via Polly.Testing
  • Dynamic pipeline configuration with hot reloading

​
Better Developer Experience

  • Unified sync/async execution with single pipeline
  • Options-based configuration for better IntelliSense
  • Improved type safety with generic builders
  • Better testability with dependency injection support

​
Additional Resources

​
Support

If you encounter issues during migration:
  1. Check the Migration Guide for specific scenarios
  2. Review the GitHub Discussions for community support
  3. Report bugs via GitHub Issues
The v7 API will continue to be supported in the Polly package for the foreseeable future, allowing you to migrate at your own pace.

Build docs developers (and LLMs) love

Get started for freeTalk to us