Http resilience readme

src/Libraries/Microsoft.Extensions.Http.Resilience/Microsoft.Extensions.Http.Resilience.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <RootNamespace>Microsoft.Extensions.Http.Resilience</RootNamespace>
-    <Description>Resilience mechanisms for HTTP Client.</Description>
+    <Description>Resilience mechanisms for HttpClient.</Description>
     <Workstream>Resilience</Workstream>
   </PropertyGroup>
 

src/Libraries/Microsoft.Extensions.Http.Resilience/README.md

@@ -1,6 +1,6 @@
 # Microsoft.Extensions.Http.Resilience
 
-Resilience mechanisms for HTTP Client.
+Resilience mechanisms for `HttpClient` built on the [Polly framework](https://www.pollydocs.org/).
 
 ## Install the package
 
@@ -18,6 +18,40 @@ Or directly in the C# project file:
 </ItemGroup>
 ```
 
+## Usage Examples
+
+When configuring an HttpClient through the client factory the following extensions can add a set of pre-configured hedging or resilience behaviors. These pipelines combine multiple strategies with pre-configured defaults.
+- The total request timeout pipeline applies an overall timeout to the execution, ensuring that the request including hedging attempts, does not exceed the configured limit.
+- The retry pipeline retries the request in case the dependency is slow or returns a transient error.
+- The bulkhead pipeline limits the maximum number of concurrent requests being send to the dependency.
+- The circuit breaker blocks the execution if too many direct failures or timeouts are detected.
+- The attempt timeout pipeline limits each request attempt duration and throws if its exceeded.
+
+### Resilience
+
+The standard resilience pipeline makes use of the above strategies to ensure HTTP requests can be sent reliably.
+
+```csharp
+var clientBuilder = services.AddHttpClient("MyClient");
+
+clientBuilder.AddStandardResilienceHandler().Configure(o =>
+{
+    o.CircuitBreaker.MinimumThroughput = 10;
+});
+```
+
+### Hedging
+
+The standard hedging pipeline uses a pool of circuit breakers to ensure that unhealthy endpoints are not hedged against. By default, the selection from pool is based on the URL Authority (scheme + host + port). It is recommended that you configure the way the strategies are selected by calling the `SelectPipelineByAuthority()` extensions. The last three strategies are applied to each individual endpoint.
+
+```csharp
+var clientBuilder = services.AddHttpClient("MyClient");
+
+clientBuilder.AddStandardHedgingHandler().Configure(o =>
+{
+    o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(10);
+});
+```
 
 ## Feedback & Contributing