From 561712c85b55dd4b16754fee0b023860a20b8f57 Mon Sep 17 00:00:00 2001
From: Martin Tomka <martintomka@microsoft.com>
Date: Tue, 26 Sep 2023 10:34:34 +0200
Subject: [PATCH] PR comments

---
 docs/migration-v8.md                   | 41 ++++++++++++++++++++++++
 src/Snippets/Docs/Migration.Timeout.cs | 44 ++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 src/Snippets/Docs/Migration.Timeout.cs

diff --git a/docs/migration-v8.md b/docs/migration-v8.md
index ec997939668..4484cfd4147 100644
--- a/docs/migration-v8.md
+++ b/docs/migration-v8.md
@@ -492,6 +492,47 @@ ResiliencePipeline<HttpResponseMessage> pipelineT = new ResiliencePipelineBuilde
 ```
 <!-- endSnippet -->
 
+## Migrating timeout policy
+
+> [!NOTE]
+> In v8, the timeout resilience strategy does not support pessimistic timeouts because they can cause thread-pool starvation and non-cancellable background tasks. To address this, you can use [this workaround](https://github.com/davidfowl/AspNetCoreDiagnosticScenarios/blob/master/AsyncGuidance.md#cancelling-uncancellable-operations) to make the action cancellable.
+
+### Timeout in v7
+
+<!-- snippet: migration-timeout-v7 -->
+```cs
+// Create sync timeout
+ISyncPolicy syncPolicy = Policy.Timeout(TimeSpan.FromSeconds(10));
+
+// Create async timeout
+IAsyncPolicy asyncPolicy = Policy.TimeoutAsync(TimeSpan.FromSeconds(10));
+
+// Create generic sync timeout
+ISyncPolicy<HttpResponseMessage> syncPolicyT = Policy.Timeout<HttpResponseMessage>(TimeSpan.FromSeconds(10));
+
+// Create generic async timeout
+IAsyncPolicy<HttpResponseMessage> asyncPolicyT = Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(10));
+```
+<!-- endSnippet -->
+
+### Timeout in v8
+
+<!-- snippet: migration-timeout-v8 -->
+```cs
+// Create pipeline with timeout. Because ResiliencePipeline supports both sync and async
+// callbacks, there is no need to define it twice.
+ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
+    .AddTimeout(TimeSpan.FromSeconds(10))
+    .Build();
+
+// Create a generic pipeline with timeout. Because ResiliencePipeline<T> supports both sync and async
+// callbacks, there is no need to define it twice.
+ResiliencePipeline<HttpResponseMessage> pipelineT = new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddTimeout(TimeSpan.FromSeconds(10))
+    .Build();
+```
+<!-- endSnippet -->
+
 ## Migrating other policies
 
 Migrating is a process similar to the one described in previous sections. Keep in mind:
diff --git a/src/Snippets/Docs/Migration.Timeout.cs b/src/Snippets/Docs/Migration.Timeout.cs
new file mode 100644
index 00000000000..9935b2b15cc
--- /dev/null
+++ b/src/Snippets/Docs/Migration.Timeout.cs
@@ -0,0 +1,44 @@
+using System.Net.Http;
+
+namespace Snippets.Docs;
+
+internal static partial class Migration
+{
+    public static void Timeout_V7()
+    {
+        #region migration-timeout-v7
+
+        // Create sync timeout
+        ISyncPolicy syncPolicy = Policy.Timeout(TimeSpan.FromSeconds(10));
+
+        // Create async timeout
+        IAsyncPolicy asyncPolicy = Policy.TimeoutAsync(TimeSpan.FromSeconds(10));
+
+        // Create generic sync timeout
+        ISyncPolicy<HttpResponseMessage> syncPolicyT = Policy.Timeout<HttpResponseMessage>(TimeSpan.FromSeconds(10));
+
+        // Create generic async timeout
+        IAsyncPolicy<HttpResponseMessage> asyncPolicyT = Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(10));
+
+        #endregion
+    }
+
+    public static void Timeout_V8()
+    {
+        #region migration-timeout-v8
+
+        // Create pipeline with timeout. Because ResiliencePipeline supports both sync and async
+        // callbacks, there is no need to define it twice.
+        ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
+            .AddTimeout(TimeSpan.FromSeconds(10))
+            .Build();
+
+        // Create a generic pipeline with timeout. Because ResiliencePipeline<T> supports both sync and async
+        // callbacks, there is no need to define it twice.
+        ResiliencePipeline<HttpResponseMessage> pipelineT = new ResiliencePipelineBuilder<HttpResponseMessage>()
+            .AddTimeout(TimeSpan.FromSeconds(10))
+            .Build();
+
+        #endregion
+    }
+}