[Resilient HTTP apps] Add a paragraph describing how to disable retries for some HTTP methods

docs/core/resilience/http-resilience.md

@@ -102,6 +102,16 @@ Additionally, these strategies handle the following exceptions:
 - `HttpRequestException`
 - `TimeoutRejectedException`
 
+#### Disable retries for a given list of HTTP methods
+
+By default, the standard resilience handler is configured to make retries for all HTTP methods. For some applications, such behavior could be undesirable or even harmful. For example, if a POST request inserts a new record to a database, then making retries for such a request could lead to data duplication. If you need to disable retries for a given list of HTTP methods you can use the <xref:Microsoft.Extensions.Http.Resilience.HttpRetryStrategyOptionsExtensions.DisableFor(Microsoft.Extensions.Http.Resilience.HttpRetryStrategyOptions,System.Net.Http.HttpMethod[])> method:
+
+:::code language="csharp" source="snippets/http-resilience/Program.RetryOptions.cs" id="disable_for":::
+
+Alternatively, you can use the <xref:Microsoft.Extensions.Http.Resilience.HttpRetryStrategyOptionsExtensions.DisableForUnsafeHttpMethods(Microsoft.Extensions.Http.Resilience.HttpRetryStrategyOptions)> method, which disables retries for `POST`, `PATCH`, `PUT`, `DELETE`, and `CONNECT` requests. According to [RFC](https://www.rfc-editor.org/rfc/rfc7231#section-4.2.1), these methods are considered unsafe; meaning their semantics are not read-only:
+
+:::code language="csharp" source="snippets/http-resilience/Program.RetryOptions.cs" id="disable_for_unsafe_http_methods":::
+
 ## Add standard hedging handler
 
 The standard hedging handler wraps the execution of the request with a standard hedging mechanism. Hedging retries slow requests in parallel.

docs/core/resilience/snippets/http-resilience/Program.RetryOptions.cs

@@ -13,4 +13,24 @@ private static void ConfigureRetryOptions(HostApplicationBuilder builder)
         builder.Services.Configure<HttpStandardResilienceOptions>(section);
         // </options>
     }
+
+    private static void DisableRetriesFor(IHttpClientBuilder httpClientBuilder)
+    {
+        // <disable_for>
+        httpClientBuilder.AddStandardResilienceHandler(options =>
+        {
+            options.Retry.DisableFor(HttpMethod.Post, HttpMethod.Delete);
+        });
+        // </disable_for>
+    }
+
+    private static void DisableRetriesForUnsafeHttpMethods(IHttpClientBuilder httpClientBuilder)
+    {
+        // <disable_for_unsafe_http_methods>
+        httpClientBuilder.AddStandardResilienceHandler(options =>
+        {
+            options.Retry.DisableForUnsafeHttpMethods();
+        });
+        // </disable_for_unsafe_http_methods>
+    }
 }