Polly.Extensions.Http

Important

The Microsoft.Extensions.Http.Polly is deprecated in favor of the new Microsoft.Extensions.Http.Resilience package, as detailed here. This new package is built on top of Polly, and it takes full advantage of the new Polly v8 features.

Polly.Extensions.Http is an extensions package containing opinionated convenience methods for configuring Polly policies to handle transient faults typical of calls through HttpClient.

Polly.Extensions.Http targets .NET Standard 1.1 and .NET Standard 2.0.

Polly is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner.

Polly is a member of the .NET Foundation!

Installing via NuGet

Install-Package Polly.Extensions.Http

This package contains a strongly-named DLL.

Convenience methods for transient faults of HttpClient calls

This repo offers opinionated convenience methods for defining Polly policies to handle transient faults which may be raised by calls through HttpClient.

using Polly.Extensions.Http;

// ..

// Handles HttpRequestException, Http status codes >= 500 (server errors) and status code 408 (request timeout)
var policy = HttpPolicyExtensions
  .HandleTransientHttpError()
  .RetryAsync(3); // A very simple retry-3-times. See https://github.com/App-vNext/Polly for the many richer Policy configuration options available.

The pre-defined set of conditions to handle can be freely extended using Polly's usual Handle and Or clauses:

// Pre-canned http fault handling plus extra http status codes
var policy = HttpPolicyExtensions
  .HandleTransientHttpError()
  .OrResult(response => (int)response.StatusCode == someStatusCode) 
  .RetryAsync(3);

// Pre-canned http fault handling plus extra exceptions
var policy = HttpPolicyExtensions
  .HandleTransientHttpError()
  .Or<TimeoutRejectedException>() // TimeoutRejectedException from Polly's TimeoutPolicy
  .RetryAsync(3);

Related overloads in Polly's 'Or' syntax are also provided:

// Handles SomeException, HttpRequestException, Http status codes >= 500 (server errors) and status code 408 (request timeout)
// ('or' syntax after your own custom 'handle' clause)
var policy = Policy
  .Handle<SomeException>()
  .OrTransientHttpError()
  .RetryAsync(3);

// Handles SomeException, Http status codes >= 500 (server errors) and status code 408 (request timeout)
// ('or' syntax after your own custom 'handle' clause)
var policy = Policy
  .Handle<SomeException>()
  .OrTransientHttpStatusCode()
  .RetryAsync(3);

Using Polly.Extensions.Http with IHttpClientFactory

Polly.Extensions.Http is ideal for creating custom Polly policies for use with IHttpClientFactory, available from ASP.NET Core 2.1.

var retryPolicy = HttpPolicyExtensions
  .HandleTransientHttpError()
  .Or<TimeoutRejectedException>() // thrown by Polly's TimeoutPolicy if the inner execution times out
  .RetryAsync(3);

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(10);  

serviceCollection.AddHttpClient("example.com", c => c.BaseAddress = new Uri("http://example.com"))
  .AddPolicyHandler(retryPolicy)
  .AddPolicyHandler(timeoutPolicy);

Official documentation

Microsoft documentation on IHttpClientFactory
Microsoft documentation on using Polly policies with IHttpClientFactory
Polly documentation on Polly and HttpClientFactory
Main Polly readme: quickstart details of all Polly policies and features
Polly wiki: deep doco on Polly features

Release notes

For details of changes by release see the change log.

3rd Party Libraries and Contributions

Fluent Assertions - A set of .NET extension methods that allow you to more naturally specify the expected outcome of a TDD or BDD-style test | Apache License 2.0 (Apache)
xUnit.net - Free, open source, community-focused unit testing tool for the .NET Framework | Apache License 2.0 (Apache)
Build powered by Cake and GitVersionTask.

Acknowledgements

Developed in collaboration between the Polly team (@reisenberger and @joelhulen) and Microsoft ASP.NET Core team members Ryan Nowak and Glenn Condron.

Instructions for Contributing

Since Polly is part of the .NET Foundation, we ask our contributors to abide by their Code of Conduct. To contribute (beyond trivial typo corrections), review and sign the .Net Foundation Contributor License Agreement. This ensures the community is free to use your contributions. The registration process can be completed entirely online.

Also, we've stood up a Slack channel for easier real-time discussion of ideas and the general direction of Polly as a whole.

License

Licensed under the terms of the New BSD License

App-vNext / Polly.Extensions.Http