diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6b5837413b2..794350c1463 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,13 +2,13 @@ ### The issue or feature being addressed - + ### Details on the issue fix or feature implementation ### Confirm the following -- [ ] I started this PR by branching from the head of the latest dev vX.Y branch, or I have rebased on the latest dev vX.Y branch, or I have merged the latest changes from the dev vX.Y branch -- [ ] I have targeted the PR to merge into the latest dev vX.Y branch as the base branch +- [ ] I started this PR by branching from the head of the default branch +- [ ] I have targeted the PR to merge into the default branch - [ ] I have included unit tests for the issue/feature - [ ] I have successfully run a local build diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5efa9aa3da..d6ea9d55c1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,3 @@ -Please see our Instructions for Contributing in the [ReadMe](https://github.com/App-vNext/Polly#instructions-for-contributing) and [wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow). +Please see our Instructions for Contributing in the [README](https://github.com/App-vNext/Polly#instructions-for-contributing) and [wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow). -Please be sure to branch from the head of the latest vX.Y.Z dev branch (rather than master) when developing contributions. +Please be sure to branch from the head of the default branch when developing contributions. diff --git a/README.md b/README.md index 806e7ed90ab..48e69798e7d 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,15 @@ We are a member of the [.NET Foundation](https://www.dotnetfoundation.org/about) [![NuGet version](https://badge.fury.io/nu/polly.svg)](https://badge.fury.io/nu/polly) [![Build status](https://ci.appveyor.com/api/projects/status/imt7dymt50346k5u?svg=true)](https://ci.appveyor.com/project/joelhulen/polly) [![Slack Status](http://www.pollytalk.org/badge.svg)](http://www.pollytalk.org) -![](https://raw.github.com/App-vNext/Polly/master/Polly-Logo.png) +![Polly logo](https://raw.github.com/App-vNext/Polly/master/Polly-Logo.png) -# Installing via NuGet - - Install-Package Polly +## Installing via NuGet +```text +Install-Package Polly +``` -# Resilience policies +## Resilience policies Polly offers multiple resilience policies: @@ -55,11 +56,11 @@ For details of supported compilation targets by version, see the [supported targ This ReadMe aims to give a quick overview of all Polly features - including enough to get you started with any policy. For deeper detail on any policy, and many other aspects of Polly, be sure also to check out the [wiki documentation](https://github.com/App-vNext/Polly/wiki). -# Usage – fault-handling, reactive policies +## Usage – fault-handling, reactive policies Fault-handling policies handle specific exceptions thrown by, or results returned by, the delegates you execute through the policy. -## Step 1 : Specify the exceptions/faults you want the policy to handle +### Step 1 : Specify the exceptions/faults you want the policy to handle ```csharp // Single exception type @@ -87,7 +88,7 @@ Policy .OrInner(ex => ex.CancellationToken != myToken) ``` -## Step 1b: (optionally) Specify return results you want to handle +### Step 1b: (optionally) Specify return results you want to handle From Polly v4.3.0 onwards, policies wrapping calls returning a `TResult` can also handle `TResult` return values: @@ -123,9 +124,9 @@ HttpResponseMessage result = await Policy For more information, see [Handling Return Values](#handing-return-values-and-policytresult) at foot of this readme. -## Step 2 : Specify how the policy should handle those faults +### Step 2 : Specify how the policy should handle those faults -### Retry +#### Retry ```csharp // Retry once @@ -158,7 +159,7 @@ Policy }); ``` -### Retry forever (until succeeds) +#### Retry forever (until succeeds) ```csharp @@ -186,7 +187,7 @@ Policy }); ``` -### Wait and retry +#### Wait and retry ```csharp // Retry, waiting a specified duration between each retry. @@ -253,9 +254,7 @@ Policy // 2 ^ 5 = 32 seconds Policy .Handle() - .WaitAndRetry(5, retryAttempt => - TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)) - ); + .WaitAndRetry(5, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt))); // Retry a specified number of times, using a function to // calculate the duration to wait between retries based on @@ -292,16 +291,14 @@ The above code demonstrates how to build common wait-and-retry patterns from scr For `WaitAndRetry` policies handling Http Status Code 429 Retry-After, see [wiki documentation](https://github.com/App-vNext/Polly/wiki/Retry#retryafter-when-the-response-specifies-how-long-to-wait). -### Wait and retry forever (until succeeds) +#### Wait and retry forever (until succeeds) ```csharp // Wait and retry forever Policy .Handle() - .WaitAndRetryForever(retryAttempt => - TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)) - ); + .WaitAndRetryForever(retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt))); // Wait and retry forever, calling an action on each retry with the // current exception and the time to wait @@ -330,7 +327,7 @@ If all retries fail, a retry policy rethrows the final exception back to the cal For more depth see also: [Retry policy documentation on wiki](https://github.com/App-vNext/Polly/wiki/Retry). -### Circuit Breaker +#### Circuit Breaker ```csharp // Break the circuit after the specified number of consecutive exceptions @@ -372,16 +369,14 @@ CircuitState.Isolated - Circuit held manually in an open state. Execution of act breaker.Isolate(); // Reset the breaker to closed state, to start accepting actions again. breaker.Reset(); - ``` Circuit-breaker policies block exceptions by throwing `BrokenCircuitException` when the circuit is broken. See: [Circuit-Breaker documentation on wiki](https://github.com/App-vNext/Polly/wiki/Circuit-Breaker). Note that circuit-breaker policies [rethrow all exceptions](https://github.com/App-vNext/Polly/wiki/Circuit-Breaker#exception-handling), even handled ones. A circuit-breaker exists to measure faults and break the circuit when too many faults occur, but does not orchestrate retries. Combine a circuit-breaker with a retry policy as needed. +#### Advanced Circuit Breaker - -### Advanced Circuit Breaker ```csharp // Break the circuit if, within any period of duration samplingDuration, // the proportion of actions resulting in a handled exception exceeds failureThreshold, @@ -403,16 +398,18 @@ Policy // Circuit state monitoring and manual controls are // available as described for CircuitBreaker above. ``` + For more detail see: [Advanced Circuit-Breaker documentation](https://github.com/App-vNext/Polly/wiki/Advanced-Circuit-Breaker) on wiki. For more information on the Circuit Breaker pattern in general see: -* [Making the Netflix API More Resilient](http://techblog.netflix.com/2011/12/making-netflix-api-more-resilient.html) -* [Circuit Breaker (Martin Fowler)](http://martinfowler.com/bliki/CircuitBreaker.html) -* [Circuit Breaker Pattern (Microsoft)](https://msdn.microsoft.com/en-us/library/dn589784.aspx) -* [Original Circuit Breaking Link](https://web.archive.org/web/20160106203951/http://thatextramile.be/blog/2008/05/the-circuit-breaker) ++ [Making the Netflix API More Resilient](http://techblog.netflix.com/2011/12/making-netflix-api-more-resilient.html) ++ [Circuit Breaker (Martin Fowler)](http://martinfowler.com/bliki/CircuitBreaker.html) ++ [Circuit Breaker Pattern (Microsoft)](https://msdn.microsoft.com/en-us/library/dn589784.aspx) ++ [Original Circuit Breaking Link](https://web.archive.org/web/20160106203951/http://thatextramile.be/blog/2008/05/the-circuit-breaker) + +#### Fallback -### Fallback ```csharp // Provide a substitute value, if an execution faults. Policy @@ -433,12 +430,11 @@ Policy { // Add extra logic to be called when the fallback is invoked, such as logging }); - ``` For more detail see: [Fallback policy documentation](https://github.com/App-vNext/Polly/wiki/Fallback) on wiki. -## Step 3 : Execute code through the policy +### Step 3 : Execute code through the policy Execute an `Action`, `Func`, or lambda delegate equivalent, through the policy. The policy governs execution of the code passed to the `.Execute()` (or similar) method. @@ -458,12 +454,12 @@ var policy = Policy .Retry(3, (exception, retryCount, context) => { var methodThatRaisedException = context["methodName"]; - Log(exception, methodThatRaisedException); + Log(exception, methodThatRaisedException); }); policy.Execute( - () => DoSomething(), - new Dictionary() {{ "methodName", "some method" }} + () => DoSomething(), + new Dictionary() {{ "methodName", "some method" }} ); // Execute a function returning a result @@ -495,7 +491,7 @@ Policy .Execute(() => DoSomething()); ``` -### Richer policy consumption patterns +#### Richer policy consumption patterns Defining and consuming the policy in the same scope, as shown above, is the most immediate way to use Polly. Consider also: @@ -509,15 +505,15 @@ public static ConfigurePollyPolicies(this IServiceCollection services) { { "RepositoryResilienceStrategy", /* define Policy or PolicyWrap strategy */ }, { "CollaboratingMicroserviceResilienceStrategy", /* define Policy or PolicyWrap strategy */ }, - { "ThirdPartyApiResilienceStrategy", /* define Policy or PolicyWrap strategy */ }, - /* etc */ + { "ThirdPartyApiResilienceStrategy", /* define Policy or PolicyWrap strategy */ }, + /* etc */ }; services.AddSingleton>(registry); } ``` -# Usage – proactive policies +## Usage – proactive policies The proactive policies add resilience strategies that are not based on handling faults which the governed code may throw or return. @@ -529,7 +525,6 @@ The proactive policies add resilience strategies that are not based on handling Optimistic timeout [operates via CancellationToken](https://github.com/App-vNext/Polly/wiki/Timeout#optimistic-timeout) and assumes delegates you execute support [co-operative cancellation](https://msdn.microsoft.com/en-us/library/dd997364.aspx). You must use `Execute/Async(...)` overloads taking a `CancellationToken`, and the executed delegate must honor that `CancellationToken`. - ```csharp // Timeout and return to the caller after 30 seconds, if the executed delegate has not completed. Optimistic timeout: Delegates should take and honour a CancellationToken. Policy @@ -604,7 +599,7 @@ Timeout policies throw `TimeoutRejectedException` when timeout occurs. For more detail see: [Timeout policy documentation](https://github.com/App-vNext/Polly/wiki/Timeout) on wiki. -### Bulkhead +#### Bulkhead ```csharp // Restrict executions through the policy to a maximum of twelve concurrent actions. @@ -633,10 +628,9 @@ int freeQueueSlots = bulkhead.QueueAvailableCount; Bulkhead policies throw `BulkheadRejectedException` if items are queued to the bulkhead when the bulkhead execution and queue are both full. - For more detail see: [Bulkhead policy documentation](https://github.com/App-vNext/Polly/wiki/Bulkhead) on wiki. -### Rate-Limit +#### Rate-Limit ```csharp // Allow up to 20 executions per second. @@ -694,9 +688,7 @@ Rate-limit policies throw `RateLimitRejectedException` if too many requests are For more detail see: [Rate-limit policy documentation](https://github.com/App-vNext/Polly/wiki/Rate-Limit) in the wiki. -
- -### Cache +#### Cache ```csharp var memoryCache = new MemoryCache(new MemoryCacheOptions()); @@ -724,12 +716,11 @@ var cachePolicy = Policy.Cache(myCacheProvider, TimeSpan.FromMinutes(5), // The key to use for caching, for a particular execution, is specified by setting the OperationKey (before v6: ExecutionKey) on a Context instance passed to the execution. Use an overload of the form shown below (or a richer overload including the same elements). // Example: "FooKey" is the cache key that will be used in the below execution. TResult result = cachePolicy.Execute(context => getFoo(), new Context("FooKey")); - ``` For richer options and details of using further cache providers see: [Cache policy documentation](https://github.com/App-vNext/Polly/wiki/Cache) on wiki. -### PolicyWrap +#### PolicyWrap ```csharp // Define a combined policy strategy, built of previously-defined policies. @@ -759,7 +750,7 @@ Reputation reps = Policy For more detail see: [PolicyWrap documentation](https://github.com/App-vNext/Polly/wiki/PolicyWrap) on wiki. -### NoOp +#### NoOp ```csharp // Define a policy which will simply cause delegates passed for execution to be executed 'as is'. @@ -768,13 +759,14 @@ For more detail see: [PolicyWrap documentation](https://github.com/App-vNext/Pol // but you simply want to pass the execution through without policy intervention. NoOpPolicy noOp = Policy.NoOp(); ``` + For more detail see: [NoOp documentation](https://github.com/App-vNext/Polly/wiki/NoOp) on wiki. -## Step 2 : Execute the policy +### Step 2 : Execute the policy -As for fault-handling policies [above](#step-3--execute-the-policy). +As for fault-handling policies [above](#step-3--execute-code-through-the-policy). -# Post-execution: capturing the result, or any final exception +## Post-execution: capturing the result, or any final exception Using the `ExecuteAndCapture(...)` methods you can capture the outcome of an execution: the methods return a `PolicyResult` instance which describes whether the outcome was a successful execution or a fault. @@ -791,7 +783,7 @@ policyResult.Result - if executing a func, the result if the call succeeded or t */ ``` -# Handing return values, and Policy<TResult> +## Handing return values, and Policy<TResult> As described at step 1b, from Polly v4.3.0 onwards, policies can handle return values and exceptions in combination: @@ -819,14 +811,14 @@ Configuring a policy with `.HandleResult(...)` or `.OrResult(. These policies must be used to execute delegates returning `TResult`, i.e.: -* `Execute(Func)` (and related overloads) -* `ExecuteAsync(Func>)` (and related overloads) ++ `Execute(Func)` (and related overloads) ++ `ExecuteAsync(Func>)` (and related overloads) ### ExecuteAndCapture<TResult>() `.ExecuteAndCapture(...)` on non-generic policies returns a `PolicyResult` with properties: -``` +```txt policyResult.Outcome - whether the call succeeded or failed policyResult.FinalException - the final exception captured; will be null if the call succeeded policyResult.ExceptionType - was the final exception an exception the policy was defined to handle (like HttpRequestException above) or an unhandled one (say Exception)? Will be null if the call succeeded. @@ -835,32 +827,30 @@ policyResult.Result - if executing a func, the result if the call succeeded; oth `.ExecuteAndCapture(Func)` on strongly-typed policies adds two properties: -``` +```txt policyResult.FaultType - was the final fault handled an exception or a result handled by the policy? Will be null if the delegate execution succeeded. policyResult.FinalHandledResult - the final fault result handled; will be null or the type's default value, if the call succeeded ``` -### State-change delegates on Policy<TResult> policies +#### State-change delegates on Policy<TResult> policies In non-generic policies handling only exceptions, state-change delegates such as `onRetry` and `onBreak` take an `Exception` parameter. In generic-policies handling `TResult` return values, state-change delegates are identical except they take a `DelegateResult` parameter in place of `Exception.` `DelegateResult` has two properties: -* `Exception // The exception just thrown if policy is in process of handling an exception (otherwise null)` -* `Result // The TResult just raised, if policy is in process of handling a result (otherwise default(TResult))` ++ `Exception // The exception just thrown if policy is in process of handling an exception (otherwise null)` ++ `Result // The TResult just raised, if policy is in process of handling a result (otherwise default(TResult))` - -### BrokenCircuitException<TResult> +#### BrokenCircuitException<TResult> Non-generic CircuitBreaker policies throw a `BrokenCircuitException` when the circuit is broken. This `BrokenCircuitException` contains the last exception (the one which caused the circuit to break) as the `InnerException`. For `CircuitBreakerPolicy` policies: -* A circuit broken due to an exception throws a `BrokenCircuitException` with `InnerException` set to the exception which triggered the break (as previously). -* A circuit broken due to handling a result throws a `BrokenCircuitException` with the `Result` property set to the result which caused the circuit to break. - -# Policy Keys and Context data ++ A circuit broken due to an exception throws a `BrokenCircuitException` with `InnerException` set to the exception which triggered the break (as previously). ++ A circuit broken due to handling a result throws a `BrokenCircuitException` with the `Result` property set to the result which caused the circuit to break. +## Policy Keys and Context data ```csharp // Identify policies with a PolicyKey, using the WithPolicyKey() extension method @@ -898,7 +888,7 @@ var customerDetails = policy.Execute(context => GetCustomer(id), For more detail see: [Keys and Context Data](https://github.com/App-vNext/Polly/wiki/Keys-And-Context-Data) on wiki. -# PolicyRegistry +## PolicyRegistry ```csharp // Create a policy registry (for example on application start-up) @@ -928,26 +918,25 @@ registry.Get>("StandardHttpResilience") Available from v5.2.0. For more detail see: [PolicyRegistry](https://github.com/App-vNext/Polly/wiki/PolicyRegistry) on wiki. - -# Asynchronous Support +## Asynchronous Support Polly fully supports asynchronous executions, using the asynchronous methods: -* `RetryAsync` -* `WaitAndRetryAsync` -* `CircuitBreakerAsync` -* (etc) -* `ExecuteAsync` -* `ExecuteAndCaptureAsync` ++ `RetryAsync` ++ `WaitAndRetryAsync` ++ `CircuitBreakerAsync` ++ (etc) ++ `ExecuteAsync` ++ `ExecuteAndCaptureAsync` In place of their synchronous counterparts: -* `Retry` -* `WaitAndRetry` -* `CircuitBreaker` -* (etc) -* `Execute` -* `ExecuteAndCapture` ++ `Retry` ++ `WaitAndRetry` ++ `CircuitBreaker` ++ (etc) ++ `Execute` ++ `ExecuteAndCapture` Async overloads exist for all policy types and for all `Execute()` and `ExecuteAndCapture()` overloads. @@ -962,11 +951,11 @@ await Policy ``` -### SynchronizationContext ### +### SynchronizationContext Async continuations and retries by default do not run on a captured synchronization context. To change this, use `.ExecuteAsync(...)` overloads taking a boolean `continueOnCapturedContext` parameter. -### Cancellation support ### +#### Cancellation support Async policy execution supports cancellation via `.ExecuteAsync(...)` overloads taking a `CancellationToken`. @@ -991,28 +980,26 @@ var response = await policy.ExecuteAsync(ct => httpClient.GetAsync(uri, ct), can From Polly v5.0, synchronous executions also support cancellation via `CancellationToken`. -# Thread safety +## Thread safety All Polly policies are fully thread-safe. You can safely re-use policies at multiple call sites, and execute through policies concurrently on different threads. While the internal operation of the policy is thread-safe, this does not magically make delegates you execute through the policy thread-safe: if delegates you execute through the policy are not thread-safe, they remain not thread-safe. - -# Interfaces +## Interfaces Polly v5.2.0 adds interfaces intended to support [`PolicyRegistry`](https://github.com/App-vNext/Polly/wiki/PolicyRegistry) and to group Policy functionality by the [interface segregation principle](https://en.wikipedia.org/wiki/Interface_segregation_principle). Polly's interfaces are not intended for coding your own policy implementations against. -## Execution interfaces: `ISyncPolicy` etc +### Execution interfaces: `ISyncPolicy` etc Execution interfaces [`ISyncPolicy`](https://github.com/App-vNext/Polly/tree/master/src/Polly.Shared/ISyncPolicy.cs), [`IAsyncPolicy`](https://github.com/App-vNext/Polly/tree/master/src/Polly.Shared/IAsyncPolicy.cs), [`ISyncPolicy`](https://github.com/App-vNext/Polly/tree/master/src/Polly.Shared/ISyncPolicyTResult.cs) and [`IAsyncPolicy`](https://github.com/App-vNext/Polly/tree/master/src/Polly.Shared/IAsyncPolicyTResult.cs) define the execution overloads available to policies targeting sync/async, and non-generic / generic calls respectively. -## Policy-kind interfaces: `ICircuitBreakerPolicy` etc +### Policy-kind interfaces: `ICircuitBreakerPolicy` etc Orthogonal to the execution interfaces, interfaces specific to the kind of Policy define properties and methods common to that type of policy. For example, [`ICircuitBreakerPolicy`](https://github.com/App-vNext/Polly/tree/master/src/Polly.Shared/CircuitBreaker/ICircuitBreakerPolicy.cs) defines - + `CircuitState CircuitState` + `Exception LastException` + `void Isolate()` @@ -1026,14 +1013,13 @@ This allows collections of similar kinds of policy to be treated as one - for ex For more detail see: [Polly and interfaces](https://github.com/App-vNext/Polly/wiki/Polly-and-interfaces) on wiki. - -# Simmy +## Simmy [Simmy](https://github.com/Polly-Contrib/Simmy) is a major new companion project adding a chaos-engineering and fault-injection dimension to Polly, through the provision of policies to selectively inject faults or latency. Head over to the [Simmy](https://github.com/Polly-Contrib/Simmy) repo to find out more. -# Custom policies +## Custom policies From Polly v7.0 it is possible to [create your own custom policies](http://www.thepollyproject.org/2019/02/13/introducing-custom-polly-policies-and-polly-contrib-custom-policies-part-i/) outside Polly. These custom policies can integrate in to all the existing goodness from Polly: the `Policy.Handle<>()` syntax; PolicyWrap; all the execution-dispatch overloads. @@ -1046,7 +1032,7 @@ For more info see our blog series: We provide a [starter template for a custom policy](https://github.com/Polly-Contrib/Polly.Contrib.CustomPolicyTemplates) for developing your own custom policy. -# Polly-Contrib +## Polly-Contrib Polly now has a [Polly-Contrib](https://github.com/Polly-Contrib) to allow the community to contribute policies or other enhancements around Polly with a low burden of ceremony. @@ -1059,7 +1045,7 @@ We also provide: Both templates contain a full project structure referencing Polly, Polly's default build targets, and a build to build and test your contrib and make a NuGet package. -## Available via Polly-Contrib +### Available via Polly-Contrib + [Polly.Contrib.WaitAndRetry](https://github.com/Polly-Contrib/Polly.Contrib.WaitAndRetry): a collection of concise helper methods for common wait-and-retry strategies; and a new jitter formula combining exponential backoff with a very even distribution of randomly-jittered retry intervals. + [Polly.Contrib.AzureFunctions.CircuitBreaker](https://github.com/Polly-Contrib/Polly.Contrib.AzureFunctions.CircuitBreaker): a distributed circuit-breaker implemented in Azure Functions; consumable in Azure Functions, or from anywhere over http. @@ -1067,163 +1053,159 @@ Both templates contain a full project structure referencing Polly, Polly's defau + [Polly.Contrib.TimingPolicy](https://github.com/Polly-Contrib/Polly.Contrib.TimingPolicy): a starter policy to publish execution timings of any call executed through Policy. + [Polly.Contrib.LoggingPolicy](https://github.com/Polly-Contrib/Polly.Contrib.LoggingPolicy): a policy simply to log handled exceptions/faults, and rethrow or bubble the fault outwards. -# 3rd Party Libraries and Contributions - -* [Fluent Assertions](https://github.com/fluentassertions/fluentassertions) - 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)](https://github.com/dennisdoomen/fluentassertions/blob/develop/LICENSE) -* [xUnit.net](https://github.com/xunit/xunit) - Free, open source, community-focused unit testing tool for the .NET Framework | [Apache License 2.0 (Apache)](https://github.com/xunit/xunit/blob/master/license.txt) -* [Ian Griffith's TimedLock](http://www.interact-sw.co.uk/iangblog/2004/04/26/yetmoretimedlocking) -* [Steven van Deursen's ReadOnlyDictionary](http://www.cuttingedge.it/blogs/steven/pivot/entry.php?id=29) (until Polly v5.0.6) -* [Stephen Cleary's AsyncEx library](https://github.com/StephenCleary/AsyncEx) for AsyncSemaphore (supports BulkheadAsync policy for .NET4.0 only) (until Polly v5.9.0) | [MIT license](https://github.com/StephenCleary/AsyncEx/blob/master/LICENSE) -* [@theraot](https://github.com/theraot)'s [ExceptionDispatchInfo implementation for .NET4.0](https://stackoverflow.com/a/31226509/) (supports Timeout policy for .NET4.0 only) (until Polly v5.9.0) including also a contribution by [@migueldeicaza](https://github.com/migueldeicaza) | Licensed under and distributed under [Creative Commons Attribution Share Alike license](https://creativecommons.org/licenses/by-sa/3.0/) per [StackExchange Terms of Service](https://stackexchange.com/legal) -* Build powered by [Cake](http://cakebuild.net/) and [GitVersionTask](https://github.com/GitTools/GitVersion). Developers powered by [Resharper](https://www.jetbrains.com/resharper/), with thanks to JetBrains for [OSS licensing](https://www.jetbrains.com/support/community/#section=open-source). - -# Acknowledgements - -* [lokad-shared-libraries](https://github.com/Lokad/lokad-shared-libraries) - Helper assemblies originally for .NET 3.5 and Silverlight 2.0 which were developed as part of the Open Source effort by Lokad.com (discontinued) | [New BSD License](https://raw.github.com/Lokad/lokad-shared-libraries/master/Lokad.Shared.License.txt) -* [@michael-wolfenden](https://github.com/michael-wolfenden) - The creator and mastermind of Polly! -* [@ghuntley](https://github.com/ghuntley) - Portable Class Library implementation. -* [@mauricedb](https://github.com/mauricedb) - Initial async implementation. -* [@robgibbens](https://github.com/RobGibbens) - Added existing async files to PCL project -* [Hacko](https://github.com/hacko-bede) - Added extra `NotOnCapturedContext` call to prevent potential deadlocks when blocking on asynchronous calls -* [@ThomasMentzel](https://github.com/ThomasMentzel) - Added ability to capture the results of executing a policy via `ExecuteAndCapture` -* [@yevhen](https://github.com/yevhen) - Added full control of whether to continue on captured synchronization context or not -* [@reisenberger](https://github.com/reisenberger) - Added full async cancellation support -* [@reisenberger](https://github.com/reisenberger) - Added async support for ContextualPolicy -* [@reisenberger](https://github.com/reisenberger) - Added ContextualPolicy support for circuit-breaker -* [@reisenberger](https://github.com/reisenberger) - Extended circuit-breaker for public monitoring and control -* [@reisenberger](https://github.com/reisenberger) - Added ExecuteAndCapture support with arbitrary context data -* [@kristianhald](https://github.com/kristianhald) and [@reisenberger](https://github.com/reisenberger) - Added AdvancedCircuitBreaker -* [@reisenberger](https://github.com/reisenberger) - Allowed async onRetry delegates to async retry policies -* [@Lumirris](https://github.com/Lumirris) - Add new Polly.Net40Async project/package supporting async for .NET40 via Microsoft.Bcl.Async -* [@SteveCote](https://github.com/SteveCote) - Added overloads to WaitAndRetry and WaitAndRetryAsync methods that accept an onRetry delegate which includes the attempt count. -* [@reisenberger](https://github.com/reisenberger) - Allowed policies to handle returned results; added strongly-typed policies Policy<TResult>;. -* [@christopherbahr](https://github.com/christopherbahr) - Added optimisation for circuit-breaker hot path. -* [@Finity](https://github.com/Finity) - Fixed circuit-breaker threshold bug. -* [@reisenberger](https://github.com/reisenberger) - Add some missing ExecuteAndCapture/Async overloads. -* [@brunolauze](https://github.com/brunolauze) - Add CancellationToken support to synchronous executions (to support TimeoutPolicy). -* [@reisenberger](https://github.com/reisenberger) - Add PolicyWrap. -* [@reisenberger](https://github.com/reisenberger) - Add Fallback policy. -* [@reisenberger](https://github.com/reisenberger) - Add PolicyKeys and context to all policy executions, as bedrock for policy events and metrics tracking executions. -* [@reisenberger](https://github.com/reisenberger), and contributions from [@brunolauze](https://github.com/brunolauze) - Add Bulkhead Isolation policy. -* [@reisenberger](https://github.com/reisenberger) - Add Timeout policy. -* [@reisenberger](https://github.com/reisenberger) - Fix .NETStandard 1.0 targeting. Remove PCL259 target. PCL259 support is provided via .NETStandard1.0 target, going forward. -* [@reisenberger](https://github.com/reisenberger) - Fix CircuitBreaker HalfOpen state and cases when breakDuration is shorter than typical call timeout. Thanks to [@vgouw](https://github.com/vgouw) and [@kharos](https://github.com/kharos) for the reports and insightful thinking. -* [@lakario](https://github.com/lakario) - Tidy CircuitBreaker LastException property. -* [@lakario](https://github.com/lakario) - Add NoOpPolicy. -* [@Julien-Mialon](https://github.com/Julien-Mialon) - Fixes, support and examples for .NETStandard compatibility with Xamarin PCL projects -* [@reisenberger](https://github.com/reisenberger) - Add mutable Context and extra overloads taking Context. Allows different parts of a policy execution to exchange data via the mutable Context travelling with each execution. -* [@ankitbko](https://github.com/ankitbko) - Add PolicyRegistry for storing and retrieving policies. -* [@reisenberger](https://github.com/reisenberger) - Add interfaces by policy type and execution type. -* [@seanfarrow](https://github.com/SeanFarrow) - Add IReadOnlyPolicyRegistry interface. -* [@kesmy](https://github.com/Kesmy) - Migrate solution to msbuild15, banish project.json and packages.config -* [@hambudi](https://github.com/hambudi) - Ensure sync TimeoutPolicy with TimeoutStrategy.Pessimistic rethrows delegate exceptions without additional AggregateException. -* [@jiimaho](https://github.com/jiimaho) and [@Extremo75](https://github.com/ExtRemo75) - Provide public factory methods for PolicyResult, to support testing. -* [@Extremo75](https://github.com/ExtRemo75) - Allow fallback delegates to take handled fault as input parameter. -* [@reisenberger](https://github.com/reisenberger) and [@seanfarrow](https://github.com/SeanFarrow) - Add CachePolicy, with interfaces for pluggable cache providers and serializers. -* Thanks to the awesome devs at [@tretton37](https://github.com/tretton37) who delivered the following as part of a one-day in-company hackathon led by [@reisenberger](https://github.com/reisenberger), sponsored by [@tretton37](https://github.com/tretton37) and convened by [@thecodejunkie](https://github.com/thecodejunkie) - * [@matst80](https://github.com/matst80) - Allow WaitAndRetry to take handled fault as an input to the sleepDurationProvider, allowing WaitAndRetry to take account of systems which specify a duration to wait as part of a fault response; eg Azure CosmosDB may specify this in `x-ms-retry-after-ms` headers or in a property to an exception thrown by the Azure CosmosDB SDK. - * [@MartinSStewart](https://github.com/martinsstewart) - Add GetPolicies() extension methods to IPolicyWrap. - * [@jbergens37](https://github.com/jbergens37) - Parallelize test running where possible, to improve overall build speed. -* [@reisenberger](https://github.com/reisenberger) - Add new .HandleInner(...) syntax for handling inner exceptions natively. -* [@rjongeneelen](https://github.com/rjongeneelen) and [@reisenberger](https://github.com/reisenberger) - Allow PolicyWrap configuration to configure policies via interfaces. -* [@reisenberger](https://github.com/reisenberger) - Performance improvements. -* [@awarrenlove](https://github.com/awarrenlove) - Add ability to calculate cache Ttl based on item to cache. -* [@erickhouse](https://github.com/erickhouse) - Add a new onBreak overload that provides the prior state on a transition to an open state. -* [@benagain](https://github.com/benagain) - Bug fix: RelativeTtl in CachePolicy now always returns a ttl relative to time item is cached. -* [@urig](https://github.com/urig) - Allow TimeoutPolicy to be configured with Timeout.InfiniteTimeSpan. -* [@reisenberger](https://github.com/reisenberger) - Integration with [IHttpClientFactory](https://github.com/aspnet/HttpClientFactory/) for ASPNET Core 2.1. -* [@freakazoid182](https://github.com/Freakazoid182) - WaitAnd/RetryForever overloads where onRetry takes the retry number as a parameter. -* [@dustyhoppe](https://github.com/dustyhoppe) - Overloads where onTimeout takes thrown exception as a parameter. -* [@flin-zap](https://github.com/flin-zap) - Catch missing async continuation control. -* [@reisenberger](https://github.com/reisenberger) - Clarify separation of sync and async policies. -* [@reisenberger](https://github.com/reisenberger) - Enable extensibility by custom policies hosted external to Polly. -* [@seanfarrow](https://github.com/SeanFarrow) - Enable collection initialization syntax for PolicyRegistry. -* [@moerwald](https://github.com/moerwald) - Code clean-ups, usage of more concise C# members. -* [@cmeeren](https://github.com/cmeeren) - Enable cache policies to cache values of default(TResult). -* [@aprooks](https://github.com/aprooks) - Build script tweaks for Mac and mono. -* [@kesmy](https://github.com/Kesmy) - Add Soucelink support, clean up cake build. -* [@simluk](https://github.com/simluk) - Fix continueOnCaptureContext not being honored in async retry implementation (bug in v7.1.0 only). -* [@jnyrup](https://github.com/jnyrup) - Upgrade tests to Fluent Assertions v5.9.0 -* [@SimonCropp](https://github.com/SimonCropp) - Add netcoreapp3.0 target; code clean-ups. -* [@aerotog](https://github.com/aerotog) and [@reisenberger](https://github.com/reisenberger) - IConcurrentPolicyRegistry methods on PolicyRegistry -* [@reisenberger](https://github.com/reisenberger) and [@martincostello](https://github.com/martincostello) - Add RateLimit policy. - -# Sample Projects - -* [Polly-Samples](https://github.com/App-vNext/Polly-Samples) contains practical examples for using various implementations of Polly. Please feel free to contribute to the Polly-Samples repository in order to assist others who are either learning Polly for the first time, or are seeking advanced examples and novel approaches provided by our generous community. - -* Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers) is a sample project demonstrating a .NET Microservices architecture and using Polly for resilience - -# Instructions for Contributing - -Please be sure to branch from the head of the latest vX.Y.Z dev branch (rather than master) when developing contributions. - -For GitHub workflow, check out our [Wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow). We are following the excellent GitHub Flow process, and would like to make sure you have all of the information needed to be a world-class contributor! +## 3rd Party Libraries and Contributions + ++ [Fluent Assertions](https://github.com/fluentassertions/fluentassertions) - 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)](https://github.com/dennisdoomen/fluentassertions/blob/develop/LICENSE) ++ [xUnit.net](https://github.com/xunit/xunit) - Free, open source, community-focused unit testing tool for the .NET Framework | [Apache License 2.0 (Apache)](https://github.com/xunit/xunit/blob/master/license.txt) ++ [Ian Griffith's TimedLock](http://www.interact-sw.co.uk/iangblog/2004/04/26/yetmoretimedlocking) ++ [Steven van Deursen's ReadOnlyDictionary](http://www.cuttingedge.it/blogs/steven/pivot/entry.php?id=29) (until Polly v5.0.6) ++ [Stephen Cleary's AsyncEx library](https://github.com/StephenCleary/AsyncEx) for AsyncSemaphore (supports BulkheadAsync policy for .NET4.0 only) (until Polly v5.9.0) | [MIT license](https://github.com/StephenCleary/AsyncEx/blob/master/LICENSE) ++ [@theraot](https://github.com/theraot)'s [ExceptionDispatchInfo implementation for .NET4.0](https://stackoverflow.com/a/31226509/) (supports Timeout policy for .NET4.0 only) (until Polly v5.9.0) including also a contribution by [@migueldeicaza](https://github.com/migueldeicaza) | Licensed under and distributed under [Creative Commons Attribution Share Alike license](https://creativecommons.org/licenses/by-sa/3.0/) per [StackExchange Terms of Service](https://stackexchange.com/legal) ++ Build powered by [Cake](http://cakebuild.net/) and [GitVersionTask](https://github.com/GitTools/GitVersion). Developers powered by [Resharper](https://www.jetbrains.com/resharper/), with thanks to JetBrains for [OSS licensing](https://www.jetbrains.com/support/community/#section=open-source). + +## Acknowledgements + ++ [lokad-shared-libraries](https://github.com/Lokad/lokad-shared-libraries) - Helper assemblies originally for .NET 3.5 and Silverlight 2.0 which were developed as part of the Open Source effort by Lokad.com (discontinued) | [New BSD License](https://raw.github.com/Lokad/lokad-shared-libraries/master/Lokad.Shared.License.txt) ++ [@michael-wolfenden](https://github.com/michael-wolfenden) - The creator and mastermind of Polly! ++ [@ghuntley](https://github.com/ghuntley) - Portable Class Library implementation. ++ [@mauricedb](https://github.com/mauricedb) - Initial async implementation. ++ [@robgibbens](https://github.com/RobGibbens) - Added existing async files to PCL project ++ [Hacko](https://github.com/hacko-bede) - Added extra `NotOnCapturedContext` call to prevent potential deadlocks when blocking on asynchronous calls ++ [@ThomasMentzel](https://github.com/ThomasMentzel) - Added ability to capture the results of executing a policy via `ExecuteAndCapture` ++ [@yevhen](https://github.com/yevhen) - Added full control of whether to continue on captured synchronization context or not ++ [@reisenberger](https://github.com/reisenberger) - Added full async cancellation support ++ [@reisenberger](https://github.com/reisenberger) - Added async support for ContextualPolicy ++ [@reisenberger](https://github.com/reisenberger) - Added ContextualPolicy support for circuit-breaker ++ [@reisenberger](https://github.com/reisenberger) - Extended circuit-breaker for public monitoring and control ++ [@reisenberger](https://github.com/reisenberger) - Added ExecuteAndCapture support with arbitrary context data ++ [@kristianhald](https://github.com/kristianhald) and [@reisenberger](https://github.com/reisenberger) - Added AdvancedCircuitBreaker ++ [@reisenberger](https://github.com/reisenberger) - Allowed async onRetry delegates to async retry policies ++ [@Lumirris](https://github.com/Lumirris) - Add new Polly.Net40Async project/package supporting async for .NET40 via Microsoft.Bcl.Async ++ [@SteveCote](https://github.com/SteveCote) - Added overloads to WaitAndRetry and WaitAndRetryAsync methods that accept an onRetry delegate which includes the attempt count. ++ [@reisenberger](https://github.com/reisenberger) - Allowed policies to handle returned results; added strongly-typed policies Policy<TResult>;. ++ [@christopherbahr](https://github.com/christopherbahr) - Added optimisation for circuit-breaker hot path. ++ [@Finity](https://github.com/Finity) - Fixed circuit-breaker threshold bug. ++ [@reisenberger](https://github.com/reisenberger) - Add some missing ExecuteAndCapture/Async overloads. ++ [@brunolauze](https://github.com/brunolauze) - Add CancellationToken support to synchronous executions (to support TimeoutPolicy). ++ [@reisenberger](https://github.com/reisenberger) - Add PolicyWrap. ++ [@reisenberger](https://github.com/reisenberger) - Add Fallback policy. ++ [@reisenberger](https://github.com/reisenberger) - Add PolicyKeys and context to all policy executions, as bedrock for policy events and metrics tracking executions. ++ [@reisenberger](https://github.com/reisenberger), and contributions from [@brunolauze](https://github.com/brunolauze) - Add Bulkhead Isolation policy. ++ [@reisenberger](https://github.com/reisenberger) - Add Timeout policy. ++ [@reisenberger](https://github.com/reisenberger) - Fix .NETStandard 1.0 targeting. Remove PCL259 target. PCL259 support is provided via .NETStandard1.0 target, going forward. ++ [@reisenberger](https://github.com/reisenberger) - Fix CircuitBreaker HalfOpen state and cases when breakDuration is shorter than typical call timeout. Thanks to [@vgouw](https://github.com/vgouw) and [@kharos](https://github.com/kharos) for the reports and insightful thinking. ++ [@lakario](https://github.com/lakario) - Tidy CircuitBreaker LastException property. ++ [@lakario](https://github.com/lakario) - Add NoOpPolicy. ++ [@Julien-Mialon](https://github.com/Julien-Mialon) - Fixes, support and examples for .NETStandard compatibility with Xamarin PCL projects ++ [@reisenberger](https://github.com/reisenberger) - Add mutable Context and extra overloads taking Context. Allows different parts of a policy execution to exchange data via the mutable Context travelling with each execution. ++ [@ankitbko](https://github.com/ankitbko) - Add PolicyRegistry for storing and retrieving policies. ++ [@reisenberger](https://github.com/reisenberger) - Add interfaces by policy type and execution type. ++ [@seanfarrow](https://github.com/SeanFarrow) - Add IReadOnlyPolicyRegistry interface. ++ [@kesmy](https://github.com/Kesmy) - Migrate solution to msbuild15, banish project.json and packages.config ++ [@hambudi](https://github.com/hambudi) - Ensure sync TimeoutPolicy with TimeoutStrategy.Pessimistic rethrows delegate exceptions without additional AggregateException. ++ [@jiimaho](https://github.com/jiimaho) and [@Extremo75](https://github.com/ExtRemo75) - Provide public factory methods for PolicyResult, to support testing. ++ [@Extremo75](https://github.com/ExtRemo75) - Allow fallback delegates to take handled fault as input parameter. ++ [@reisenberger](https://github.com/reisenberger) and [@seanfarrow](https://github.com/SeanFarrow) - Add CachePolicy, with interfaces for pluggable cache providers and serializers. ++ Thanks to the awesome devs at [@tretton37](https://github.com/tretton37) who delivered the following as part of a one-day in-company hackathon led by [@reisenberger](https://github.com/reisenberger), sponsored by [@tretton37](https://github.com/tretton37) and convened by [@thecodejunkie](https://github.com/thecodejunkie) + + [@matst80](https://github.com/matst80) - Allow WaitAndRetry to take handled fault as an input to the sleepDurationProvider, allowing WaitAndRetry to take account of systems which specify a duration to wait as part of a fault response; eg Azure CosmosDB may specify this in `x-ms-retry-after-ms` headers or in a property to an exception thrown by the Azure CosmosDB SDK. + + [@MartinSStewart](https://github.com/martinsstewart) - Add GetPolicies() extension methods to IPolicyWrap. + + [@jbergens37](https://github.com/jbergens37) - Parallelize test running where possible, to improve overall build speed. ++ [@reisenberger](https://github.com/reisenberger) - Add new `.HandleInner(...)` syntax for handling inner exceptions natively. ++ [@rjongeneelen](https://github.com/rjongeneelen) and [@reisenberger](https://github.com/reisenberger) - Allow PolicyWrap configuration to configure policies via interfaces. ++ [@reisenberger](https://github.com/reisenberger) - Performance improvements. ++ [@awarrenlove](https://github.com/awarrenlove) - Add ability to calculate cache Ttl based on item to cache. ++ [@erickhouse](https://github.com/erickhouse) - Add a new onBreak overload that provides the prior state on a transition to an open state. ++ [@benagain](https://github.com/benagain) - Bug fix: RelativeTtl in CachePolicy now always returns a ttl relative to time item is cached. ++ [@urig](https://github.com/urig) - Allow TimeoutPolicy to be configured with Timeout.InfiniteTimeSpan. ++ [@reisenberger](https://github.com/reisenberger) - Integration with [IHttpClientFactory](https://github.com/aspnet/HttpClientFactory/) for ASPNET Core 2.1. ++ [@freakazoid182](https://github.com/Freakazoid182) - WaitAnd/RetryForever overloads where onRetry takes the retry number as a parameter. ++ [@dustyhoppe](https://github.com/dustyhoppe) - Overloads where onTimeout takes thrown exception as a parameter. ++ [@flin-zap](https://github.com/flin-zap) - Catch missing async continuation control. ++ [@reisenberger](https://github.com/reisenberger) - Clarify separation of sync and async policies. ++ [@reisenberger](https://github.com/reisenberger) - Enable extensibility by custom policies hosted external to Polly. ++ [@seanfarrow](https://github.com/SeanFarrow) - Enable collection initialization syntax for PolicyRegistry. ++ [@moerwald](https://github.com/moerwald) - Code clean-ups, usage of more concise C# members. ++ [@cmeeren](https://github.com/cmeeren) - Enable cache policies to cache values of default(TResult). ++ [@aprooks](https://github.com/aprooks) - Build script tweaks for Mac and mono. ++ [@kesmy](https://github.com/Kesmy) - Add Soucelink support, clean up cake build. ++ [@simluk](https://github.com/simluk) - Fix continueOnCaptureContext not being honored in async retry implementation (bug in v7.1.0 only). ++ [@jnyrup](https://github.com/jnyrup) - Upgrade tests to Fluent Assertions v5.9.0 ++ [@SimonCropp](https://github.com/SimonCropp) - Add netcoreapp3.0 target; code clean-ups. ++ [@aerotog](https://github.com/aerotog) and [@reisenberger](https://github.com/reisenberger) - IConcurrentPolicyRegistry methods on PolicyRegistry ++ [@reisenberger](https://github.com/reisenberger) and [@martincostello](https://github.com/martincostello) - Add RateLimit policy. + +## Sample Projects + ++ [Polly-Samples](https://github.com/App-vNext/Polly-Samples) contains practical examples for using various implementations of Polly. Please feel free to contribute to the Polly-Samples repository in order to assist others who are either learning Polly for the first time, or are seeking advanced examples and novel approaches provided by our generous community. + ++ Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers) is a sample project demonstrating a .NET Microservices architecture and using Polly for resilience + +## Instructions for Contributing + +Please be sure to branch from the head of the default branch when developing contributions. + +For GitHub workflow, check out our [Wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow). Since Polly is part of the .NET Foundation, we ask our contributors to abide by their [Code of Conduct](https://www.dotnetfoundation.org/code-of-conduct). To contribute (beyond trivial typo corrections), review and sign the [.NET Foundation Contributor License Agreement](https://cla.dotnetfoundation.org/). 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](http://www.pollytalk.org) channel for easier real-time discussion of ideas and the general direction of Polly as a whole. Be sure to [join the conversation](http://www.pollytalk.org) today! -# License +## License Licensed under the terms of the [New BSD License](http://opensource.org/licenses/BSD-3-Clause) -# Blogs, podcasts, courses, e-books, architecture samples and videos around Polly +## Blogs, podcasts, courses, e-books, architecture samples and videos around Polly When we discover an interesting write-up on Polly, we'll add it to this list. If you have a blog post you'd like to share, please submit a PR! -## Blog posts -* [Try .NET Samples of Polly, the .NET Resilience Framework](https://github.com/bryanjhogan/trydotnet-polly) - by [Bryan Hogan](https://nodogmablog.bryanhogan.net/) -* [Create exceptional interactive documentation with Try .NET - The Polly NuGet library did!](https://www.hanselman.com/blog/CreateExceptionalInteractiveDocumentationWithTryNETThePollyNuGetLibraryDid.aspx) - by [Scott Hanselman](https://www.hanselman.com/about/) (writing about the work of Bryan Hogan) -* [Adding resilience and Transient Fault handling to your .NET Core HttpClient with Polly](https://www.hanselman.com/blog/AddingResilienceAndTransientFaultHandlingToYourNETCoreHttpClientWithPolly.aspx) - by [Scott Hanselman](https://www.hanselman.com/about/) -* [Reliable Event Processing in Azure Functions](https://hackernoon.com/reliable-event-processing-in-azure-functions-37054dc2d0fc) - by [Jeff Hollan](https://hackernoon.com/@jeffhollan) -* [Optimally configuring ASPNET Core HttpClientFactory](https://rehansaeed.com/optimally-configuring-asp-net-core-httpclientfactory/) including with Polly policies - by [Muhammad Rehan Saeed](https://twitter.com/RehanSaeedUK/) -* [Integrating HttpClientFactory with Polly for transient fault handling](https://www.stevejgordon.co.uk/httpclientfactory-using-polly-for-transient-fault-handling) - by [Steve Gordon](https://www.stevejgordon.co.uk/) -* [Resilient network connectivity in Xamarin Forms](https://xamarinhelp.com/resilient-network-connectivity-xamarin-forms/) - by [Adam Pedley](http://xamarinhelp.com/contact/) -* [Policy recommendations for Azure Cognitive Services](http://www.thepollyproject.org/2018/03/06/policy-recommendations-for-azure-cognitive-services/) - by [Joel Hulen](http://www.thepollyproject.org/author/joel/) -* [Using Polly with F# async workflows](http://blog.ploeh.dk/2017/05/30/using-polly-with-f-async-workflows/) - by [Mark Seemann](http://blog.ploeh.dk/about/) -* [Building resilient applications with Polly](http://elvanydev.com/resilience-with-polly/) (with focus on Azure SQL transient errors) - by [Geovanny Alzate Sandoval](https://github.com/vany0114) -* [Azure SQL transient errors](https://hackernoon.com/azure-sql-transient-errors-7625ad6e0a06) - by [Mattias Karlsson](https://hackernoon.com/@devlead) -* [Polly series on No Dogma blog](http://nodogmablog.bryanhogan.net/tag/polly/) - by [Bryan Hogan](https://twitter.com/bryanjhogan) -* [Polly 5.0 - a wider resilience framework!](http://www.thepollyproject.org/2016/10/25/polly-5-0-a-wider-resilience-framework/) - by [Dylan Reisenberger](http://www.thepollyproject.org/author/dylan/) -* [Implementing the retry pattern in c sharp using Polly](https://alastaircrabtree.com/implementing-the-retry-pattern-using-polly/) - by [Alastair Crabtree](https://alastaircrabtree.com/about/) -* [NuGet Package of the Week: Polly wanna fluently express transient exception handling policies in .NET?](https://www.hanselman.com/blog/NuGetPackageOfTheWeekPollyWannaFluentlyExpressTransientExceptionHandlingPoliciesInNET.aspx) - by [Scott Hanselman](https://www.hanselman.com/about/) -* [Exception handling policies with Polly](http://putridparrot.com/blog/exception-handling-policies-with-polly/) - by [Mark Timmings](http://putridparrot.com/blog/about/) -* [When you use the Polly circuit-breaker, make sure you share your Policy instances!](https://andrewlock.net/when-you-use-the-polly-circuit-breaker-make-sure-you-share-your-policy-instances-2/) - by [Andrew Lock](https://andrewlock.net/about/) -* [Polly is Repetitive, and I love it!](http://www.appvnext.com/blog/2015/11/19/polly-is-repetitive-and-i-love-it) - by [Joel Hulen](http://www.thepollyproject.org/author/joel/) -* [Using the Context to Obtain the Retry Count for Diagnostics](https://www.stevejgordon.co.uk/polly-using-context-to-obtain-retry-count-diagnostics) - by [Steve Gordon](https://twitter.com/stevejgordon) -* [Passing an ILogger to Polly Policies](https://www.stevejgordon.co.uk/passing-an-ilogger-to-polly-policies) - by [Steve Gordon](https://twitter.com/stevejgordon) -* [Using Polly and Flurl to improve your website](https://jeremylindsayni.wordpress.com/2019/01/01/using-polly-and-flurl-to-improve-your-website/) - by Jeremy Lindsay. -* [Exploring the Polly.Contrib.WaitAndRetry helpers](https://hyr.mn/Polly-wait-and-retry/) - by [Ben Hyrman](https://twitter.com/hyrmn), who also wrote most of the Polly.Contrib.WaitAndRetry documentation. - -## Podcasts - -* June 2018: [DotNetRocks features Polly](https://www.dotnetrocks.com/?show=1556) as [Carl Franklin](https://twitter.com/carlfranklin) and [Richard Campbell](https://twitter.com/richcampbell) chat with [Dylan Reisenberger](https://twitter.com/softwarereisen) about policy patterns, and the new ASP NET Core 2.1 integration with IHttpClientFactory. +### Blog posts -* April 2017: [Dylan Reisenberger](https://twitter.com/softwarereisen) sits down virtually with [Bryan Hogan](https://twitter.com/bryanjhogan) of [NoDogmaBlog](http://nodogmablog.bryanhogan.net/) for an [Introduction to Polly podcast](http://nodogmapodcast.bryanhogan.net/71-dylan-reisenberger-the-polly-project/). Why do I need Polly? History of the Polly project. What do we mean by resilience and transient faults? How retry and circuit-breaker help. Exponential backoff. Stability patterns. Bulkhead isolation. Future directions (as at April 2017). ++ [Try .NET Samples of Polly, the .NET Resilience Framework](https://github.com/bryanjhogan/trydotnet-polly) - by [Bryan Hogan](https://nodogmablog.bryanhogan.net/) ++ [Create exceptional interactive documentation with Try .NET - The Polly NuGet library did!](https://www.hanselman.com/blog/CreateExceptionalInteractiveDocumentationWithTryNETThePollyNuGetLibraryDid.aspx) - by [Scott Hanselman](https://www.hanselman.com/about/) (writing about the work of Bryan Hogan) ++ [Adding resilience and Transient Fault handling to your .NET Core HttpClient with Polly](https://www.hanselman.com/blog/AddingResilienceAndTransientFaultHandlingToYourNETCoreHttpClientWithPolly.aspx) - by [Scott Hanselman](https://www.hanselman.com/about/) ++ [Reliable Event Processing in Azure Functions](https://hackernoon.com/reliable-event-processing-in-azure-functions-37054dc2d0fc) - by [Jeff Hollan](https://hackernoon.com/@jeffhollan) ++ [Optimally configuring ASPNET Core HttpClientFactory](https://rehansaeed.com/optimally-configuring-asp-net-core-httpclientfactory/) including with Polly policies - by [Muhammad Rehan Saeed](https://twitter.com/RehanSaeedUK/) ++ [Integrating HttpClientFactory with Polly for transient fault handling](https://www.stevejgordon.co.uk/httpclientfactory-using-polly-for-transient-fault-handling) - by [Steve Gordon](https://www.stevejgordon.co.uk/) ++ [Resilient network connectivity in Xamarin Forms](https://xamarinhelp.com/resilient-network-connectivity-xamarin-forms/) - by [Adam Pedley](http://xamarinhelp.com/contact/) ++ [Policy recommendations for Azure Cognitive Services](http://www.thepollyproject.org/2018/03/06/policy-recommendations-for-azure-cognitive-services/) - by [Joel Hulen](http://www.thepollyproject.org/author/joel/) ++ [Using Polly with F# async workflows](http://blog.ploeh.dk/2017/05/30/using-polly-with-f-async-workflows/) - by [Mark Seemann](http://blog.ploeh.dk/about/) ++ [Building resilient applications with Polly](http://elvanydev.com/resilience-with-polly/) (with focus on Azure SQL transient errors) - by [Geovanny Alzate Sandoval](https://github.com/vany0114) ++ [Azure SQL transient errors](https://hackernoon.com/azure-sql-transient-errors-7625ad6e0a06) - by [Mattias Karlsson](https://hackernoon.com/@devlead) ++ [Polly series on No Dogma blog](http://nodogmablog.bryanhogan.net/tag/polly/) - by [Bryan Hogan](https://twitter.com/bryanjhogan) ++ [Polly 5.0 - a wider resilience framework!](http://www.thepollyproject.org/2016/10/25/polly-5-0-a-wider-resilience-framework/) - by [Dylan Reisenberger](http://www.thepollyproject.org/author/dylan/) ++ [Implementing the retry pattern in c sharp using Polly](https://alastaircrabtree.com/implementing-the-retry-pattern-using-polly/) - by [Alastair Crabtree](https://alastaircrabtree.com/about/) ++ [NuGet Package of the Week: Polly wanna fluently express transient exception handling policies in .NET?](https://www.hanselman.com/blog/NuGetPackageOfTheWeekPollyWannaFluentlyExpressTransientExceptionHandlingPoliciesInNET.aspx) - by [Scott Hanselman](https://www.hanselman.com/about/) ++ [Exception handling policies with Polly](http://putridparrot.com/blog/exception-handling-policies-with-polly/) - by [Mark Timmings](http://putridparrot.com/blog/about/) ++ [When you use the Polly circuit-breaker, make sure you share your Policy instances!](https://andrewlock.net/when-you-use-the-polly-circuit-breaker-make-sure-you-share-your-policy-instances-2/) - by [Andrew Lock](https://andrewlock.net/about/) ++ [Polly is Repetitive, and I love it!](http://www.appvnext.com/blog/2015/11/19/polly-is-repetitive-and-i-love-it) - by [Joel Hulen](http://www.thepollyproject.org/author/joel/) ++ [Using the Context to Obtain the Retry Count for Diagnostics](https://www.stevejgordon.co.uk/polly-using-context-to-obtain-retry-count-diagnostics) - by [Steve Gordon](https://twitter.com/stevejgordon) ++ [Passing an ILogger to Polly Policies](https://www.stevejgordon.co.uk/passing-an-ilogger-to-polly-policies) - by [Steve Gordon](https://twitter.com/stevejgordon) ++ [Using Polly and Flurl to improve your website](https://jeremylindsayni.wordpress.com/2019/01/01/using-polly-and-flurl-to-improve-your-website/) - by Jeremy Lindsay. ++ [Exploring the Polly.Contrib.WaitAndRetry helpers](https://hyr.mn/Polly-wait-and-retry/) - by [Ben Hyrman](https://twitter.com/hyrmn), who also wrote most of the Polly.Contrib.WaitAndRetry documentation. -## PluralSight course +### Podcasts -* [Bryan Hogan](https://twitter.com/bryanjhogan) of the [NoDogmaBlog](http://nodogmablog.bryanhogan.net/) has authored a [PluralSight course on Polly](https://www.pluralsight.com/courses/polly-fault-tolerant-web-service-requests). The course takes you through all the major features of Polly, with an additional module added in the fall of 2018 on Http Client Factory. The course examples are based around using Polly for fault tolerance when calling remote web services, but the principles and techniques are applicable to any context in which Polly may be used. ++ June 2018: [DotNetRocks features Polly](https://www.dotnetrocks.com/?show=1556) as [Carl Franklin](https://twitter.com/carlfranklin) and [Richard Campbell](https://twitter.com/richcampbell) chat with [Dylan Reisenberger](https://twitter.com/softwarereisen) about policy patterns, and the new ASP NET Core 2.1 integration with IHttpClientFactory. ++ April 2017: [Dylan Reisenberger](https://twitter.com/softwarereisen) sits down virtually with [Bryan Hogan](https://twitter.com/bryanjhogan) of [NoDogmaBlog](http://nodogmablog.bryanhogan.net/) for an [Introduction to Polly podcast](http://nodogmapodcast.bryanhogan.net/71-dylan-reisenberger-the-polly-project/). Why do I need Polly? History of the Polly project. What do we mean by resilience and transient faults? How retry and circuit-breaker help. Exponential backoff. Stability patterns. Bulkhead isolation. Future directions (as at April 2017). -## Sample microservices architecture and e-book +### PluralSight course -### Sample microservices architecture ++ [Bryan Hogan](https://twitter.com/bryanjhogan) of the [NoDogmaBlog](http://nodogmablog.bryanhogan.net/) has authored a [PluralSight course on Polly](https://www.pluralsight.com/courses/polly-fault-tolerant-web-service-requests). The course takes you through all the major features of Polly, with an additional module added in the fall of 2018 on Http Client Factory. The course examples are based around using Polly for fault tolerance when calling remote web services, but the principles and techniques are applicable to any context in which Polly may be used. -* [Cesar de la Torre](https://github.com/CESARDELATORRE) produced the Microsoft [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers), a sample project demonstrating a .NET Microservices architecture. The project uses Polly retry and circuit-breaker policies for resilience in calls to microservices, and in establishing connections to transports such as RabbitMQ. +### Sample microservices architecture and e-book -### e-book +#### Sample microservices architecture -* Accompanying the project is a [.NET Microservices Architecture ebook](https://www.microsoft.com/net/download/thank-you/microservices-architecture-ebook) with an extensive section (section 8) on using Polly for resilience, to which [Dylan Reisenberger](https://twitter.com/softwarereisen) contributed. The e-book and code is now (June 2018) updated for using the latest ASP NET Core 2.1 features, [Polly with IHttpClientFactory](https://github.com/App-vNext/Polly/wiki/Polly-and-HttpClientFactory). ++ [Cesar de la Torre](https://github.com/CESARDELATORRE) produced the Microsoft [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers), a sample project demonstrating a .NET Microservices architecture. The project uses Polly retry and circuit-breaker policies for resilience in calls to microservices, and in establishing connections to transports such as RabbitMQ. -## Twitter +#### e-book -* Follow [Dylan Reisenberger on twitter](https://twitter.com/softwarereisen) for notification of new Polly releases, advance notice of new proposals, tweets of interesting resilience articles (no junk). ++ Accompanying the project is a [.NET Microservices Architecture ebook](https://www.microsoft.com/net/download/thank-you/microservices-architecture-ebook) with an extensive section (section 8) on using Polly for resilience, to which [Dylan Reisenberger](https://twitter.com/softwarereisen) contributed. The e-book and code is now (June 2018) updated for using the latest ASP NET Core 2.1 features, [Polly with IHttpClientFactory](https://github.com/App-vNext/Polly/wiki/Polly-and-HttpClientFactory). ## Videos -* [Robust Applications with Polly, the .NET Resilience Framework](https://www.infoq.com/presentations/polly), Bryan Hogan introduces Polly and explains how to use it to build a fault tolerant application. -* From MVP [Houssem Dellai](https://github.com/HoussemDellai), a [YouTube video on How to use Polly with Xamarin Apps](https://www.youtube.com/watch?v=7vsN0RkFN_E), covering wait-and-retry and discussing circuit-breaker policy with a demonstration in Xamarin Forms. Here is the [source code](https://github.com/HoussemDellai/ResilientHttpClient) of the application demonstrated in the video. Draws on the [`ResilientHttpClient`](https://github.com/dotnet-architecture/eShopOnContainers/blob/dev/src/BuildingBlocks/Resilience/Resilience.Http/ResilientHttpClient.cs) from Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers). -* In the video, [.NET Rocks Live with Jon Skeet and Bill Wagner](https://youtu.be/LCj7h7ZoHA8?t=1617), Bill Wagner discusses Polly. -* Scott Allen discusses Polly during his [Building for Resiliency and Scale in the Cloud](https://youtu.be/SFLu6jZWXGs?t=1440) presentation at NDC. -* [ASP.NET Community Standup April 24, 2018](https://youtu.be/k0Xy-5zE9to?t=12m22s): Damian Edwards, Jon Galloway and Scott Hanselman discuss Scott Hanselman's blog on [Polly with IHttpClientFactory](https://www.hanselman.com/blog/AddingResilienceAndTransientFaultHandlingToYourNETCoreHttpClientWithPolly.aspx) and the [Polly team documentation on IHttpClientFactory](https://github.com/App-vNext/Polly/wiki/Polly-and-HttpClientFactory). Interesting background discussion also on feature richness and the importance of good documentation. ++ [Robust Applications with Polly, the .NET Resilience Framework](https://www.infoq.com/presentations/polly), Bryan Hogan introduces Polly and explains how to use it to build a fault tolerant application. ++ From MVP [Houssem Dellai](https://github.com/HoussemDellai), a [YouTube video on How to use Polly with Xamarin Apps](https://www.youtube.com/watch?v=7vsN0RkFN_E), covering wait-and-retry and discussing circuit-breaker policy with a demonstration in Xamarin Forms. Here is the [source code](https://github.com/HoussemDellai/ResilientHttpClient) of the application demonstrated in the video. Draws on the [`ResilientHttpClient`](https://github.com/dotnet-architecture/eShopOnContainers/blob/dev/src/BuildingBlocks/Resilience/Resilience.Http/ResilientHttpClient.cs) from Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers). ++ In the video, [.NET Rocks Live with Jon Skeet and Bill Wagner](https://youtu.be/LCj7h7ZoHA8?t=1617), Bill Wagner discusses Polly. ++ Scott Allen discusses Polly during his [Building for Resiliency and Scale in the Cloud](https://youtu.be/SFLu6jZWXGs?t=1440) presentation at NDC. ++ [ASP.NET Community Standup April 24, 2018](https://youtu.be/k0Xy-5zE9to?t=12m22s): Damian Edwards, Jon Galloway and Scott Hanselman discuss Scott Hanselman's blog on [Polly with IHttpClientFactory](https://www.hanselman.com/blog/AddingResilienceAndTransientFaultHandlingToYourNETCoreHttpClientWithPolly.aspx) and the [Polly team documentation on IHttpClientFactory](https://github.com/App-vNext/Polly/wiki/Polly-and-HttpClientFactory). Interesting background discussion also on feature richness and the importance of good documentation.