Add remark about timeout scope on HttpCompletionOptions enum (#10750)

* Add remark about timeout scope on HttpCompletionOptions enum

* Add EnsureStatusCode invokation to illustrate the point of the ResponseHeadersRead option

* Clarify the scenario

* Replace 'see' tags with 'xref'

* Move code sample to standalone snippet

* Fully qualify HttpCompletionOption xref in markdown

* Apply suggestions from code review about MaxResponseContentBufferSize and rewording

Co-authored-by: Miha Zupan <mihazupan.zupan1@gmail.com>

* Bump sample to .NET 9 (using new LoadIntoBufferAsync overload)

---------

Co-authored-by: FERNAN OVIEDO CANDELARESI <feoviedo@microsoft.com>
Co-authored-by: Miha Zupan <mihazupan.zupan1@gmail.com>

Author: 3 people

snippets/csharp/System.Net.Http/HttpCompletionOption/HttpCompletionOptionSnippets.cs

@@ -0,0 +1,39 @@
+using System;
+using System.Net.Http;
+using System.Threading.Tasks;
+
+namespace HttpCompletionOptionSnippets
+{
+    class HttpCompletionOptionSnippets
+    {
+        public static async Task RunAsync()
+        {
+            //<SnippetHttpCompletionOption>
+            using var httpClient = new HttpClient();
+            httpClient.Timeout = TimeSpan.FromSeconds(30);
+            httpClient.MaxResponseContentBufferSize = 1_000; // This will be ignored
+
+            // Because we're specifying the ResponseHeadersRead option,
+            // the 30-second timeout applies only up until the headers are received.
+            // It does not affect future operations that interact with the response content.
+            using HttpResponseMessage response = await httpClient.GetAsync(
+                "http://localhost:12345/",
+                HttpCompletionOption.ResponseHeadersRead);
+
+            // Do other checks that don't rely on the content first, like status code validation.
+            response.EnsureSuccessStatusCode();
+
+            // Since the HttpClient.Timeout will not apply to reading the content,
+            // you must enforce it yourself, for example by using a CancellationTokenSource.
+            using var cancellationSource = new CancellationTokenSource(TimeSpan.FromSeconds(15));
+            
+            // If you wish to enforce the MaxResponseContentBufferSize limit as well,
+            // you can do so by calling the LoadIntoBufferAsync helper first.
+            await response.Content.LoadIntoBufferAsync(1_000, cancellationSource.Token);
+
+            // Make sure to pass the CancellationToken to all methods.
+            string content = await response.Content.ReadAsStringAsync(cancellationSource.Token);
+            //</SnippetHttpCompletionOption>
+        }
+    }
+}

snippets/csharp/System.Net.Http/HttpCompletionOption/HttpCompletionOptionSnippets.csproj

@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>

snippets/csharp/System.Net.Http/HttpCompletionOption/Program.cs

@@ -0,0 +1,15 @@
+using System;
+
+namespace HttpCompletionOptionSnippets
+{
+    class MetadataReaderSnippets
+    {
+        class Program
+        {
+            static async Task Main()
+            {
+                await HttpCompletionOptionSnippets.RunAsync();
+            }
+        }
+    }
+}

xml/System.Net.Http/HttpCompletionOption.xml

@@ -36,7 +36,21 @@
   </Base>
   <Docs>
     <summary>Indicates if <see cref="T:System.Net.Http.HttpClient" /> operations should be considered completed either as soon as a response is available, or after reading the entire response message including the content.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!WARNING]
+> The <xref:System.Net.Http.HttpCompletionOption> value affects the scope of the timeout specified in the <xref:System.Net.Http.HttpClient> options when reading a response. The timeout on the <xref:System.Net.Http.HttpClient> always applies on the relevant invoked methods up until the point where those methods complete/return. Crucially, when using the <xref:System.Net.Http.HttpCompletionOption.ResponseHeadersRead> option, the timeout applies only up to where the headers end and the content starts. The content reading operation needs to be timed out separately in case the server promptly returns the status line and headers but takes too long to return the content.
+> This consideration also applies to the <xref:System.Net.Http.HttpClient.MaxResponseContentBufferSize%2A> property. The limit is only enforced when using <xref:System.Net.Http.HttpCompletionOption.ResponseContentRead>.
+> Below is an example illustrating this point:
+
+ :::code language="csharp" source="~/snippets/csharp/System.Net.Http/HttpCompletionOption/HttpCompletionOptionSnippets.cs" id="SnippetHttpCompletionOption":::
+
+ ]]>
+      </format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="ResponseContentRead">