Add remark about timeout scope on HttpCompletionOptions enum #10750
Conversation
dotnet-policy-service
bot
added
the
community-contribution
|
Tagging subscribers to this area: @dotnet/ncl |
| ## Remarks | ||
| The <xref:HttpCompletionOption> value effectively affects the scope of the timeout specified in the <see cref="T:System.Net.Http.HttpClient" /> operation options when reading a response. The timeout on the <see cref="T:System.Net.Http.HttpClient" /> always applies on the relevant invoked methods up until the point where those methods complete/return. Crucially, when using the <see cref="F: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. Below is an example illustrating this point: | ||
|
|
||
| ```csharp |
There was a problem hiding this comment.
I only have an example for C#, yet the article is written for F#, VB and C++ too. Should I add examples for those languages as well?
| @@ -36,7 +36,27 @@ | |||
| </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> | |||
There was a problem hiding this comment.
The .NET docs guidelines mention an ongoing effort for all API documentation to converge into triple slash comments in source code: https://learn.microsoft.com/en-us/contribute/content/dotnet/api-documentation
However, I don't think the System.Net.Http namespace has gone through this process yet, since there's no documentation in source code: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Net.Http/src/System/Net/Http/HttpCompletionOption.cs.
Hence, I'm doing the edit directly on the backing XML documentation page.
|
Learn Build status updates of commit 175f557:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Net.Http/HttpCompletionOption.xml | View | Details |
xml/System.Net.Http/HttpCompletionOption.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'HttpCompletionOption'. - Line 0, Column 0: [Warning: disallowed-html-tag - See documentation]
HTML tag 'see' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder. - Line 0, Column 0: [Warning: disallowed-html-tag - See documentation]
HTML tag 'see' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder. - Line 0, Column 0: [Warning: disallowed-html-tag - See documentation]
HTML tag 'see' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit 87b4042:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Net.Http/HttpCompletionOption.xml | View | Details |
xml/System.Net.Http/HttpCompletionOption.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'HttpCompletionOption'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
| // Do other stuff that doesn't rely on the content first, like status code validation | ||
| response.EnsureSuccessStatusCode(); | ||
|
|
||
| var content = await response.Content.ReadAsStringAsync(); // NO TIMEOUT |
There was a problem hiding this comment.
The solution is different for .NET Framework vs .NET. In .NET, ReadAsStringAsync overrides accept a CancellationToken: https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpcontent.readasstringasync?view=net-9.0#system-net-http-httpcontent-readasstringasync(system-threading-cancellationtoken). In .NET Framework, this override doesn't exist, and so this workaround is usually used by developers: https://stackoverflow.com/questions/25985416/how-can-i-set-a-timeout-for-an-async-function-that-doesnt-accept-a-cancellation.
Adding this to the example would mean either:
a) Adding code with conditional compilation (#if NETFRAMEWORK /*timeout workaround*/ #else /*cancellation token version*/ #endif)
b) Adding separate examples for .NET vs .NET Framework
I don't know if this take away clarity from the point we're illustrating with the example though, and I don't know what the community's preference would be for such case.
|
Learn Build status updates of commit 1a44c31:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Net.Http/HttpCompletionOption.xml | View | Details | |
| snippets/csharp/System.Net.Http/HttpCompletionOption/HttpCompletionOptionSnippets.cs | ✅Succeeded | View | |
| snippets/csharp/System.Net.Http/HttpCompletionOption/HttpCompletionOptionSnippets.csproj | ✅Succeeded | ||
| snippets/csharp/System.Net.Http/HttpCompletionOption/Program.cs | ✅Succeeded |
xml/System.Net.Http/HttpCompletionOption.xml
- Line 0, Column 0: [Warning: xref-not-found - See documentation]
Cross reference not found: 'HttpCompletionOption'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit 1c8336f: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
@dotnet-policy-service agree company="Microsoft" |
Summary
Update the HttpCompletionOption enum docs to clarify its effect on the HttpClient timeout.
Issue
HttpCompletionOptions effectively affect the scope of the timeout on HttpClient operations. The timeout always applies up until the HTTP client operations complete. Because HttpCompletionOptions control when the operations complete, they effectively change when the timeout stops applying. This might be implicit and obvious in hindsight, but it's routinely overlooked by developers. This MVP article is frequently cited by developers using ResponseHeadersRead, yet the article mentions nothing about the timeout scope: https://www.stevejgordon.co.uk/using-httpcompletionoption-responseheadersread-to-improve-httpclient-performance-dotnet
Solution
Update the HttpCompletionOption enum docs to explicitly call this behavior out.