Skip to content

Collected fixes for WinHttpHandler #10638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 14, 2024
Merged

Collected fixes for WinHttpHandler #10638

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
df5f6d1
Fix default value for AutomaticDecompression
ManickaP Oct 21, 2024
1dbfa18
Remove non-sensical sentence from summary
ManickaP Oct 21, 2024
f36f2ff
Fix MaxResponseHeadersLength
ManickaP Nov 4, 2024
40d5669
DefaultProxyCredentials
ManickaP Nov 6, 2024
bf64f0d
Fix docs about ssl protocols default
ManickaP Nov 11, 2024
3c26ae2
Remove remarks
ManickaP Nov 14, 2024
2e3e486
Update xml/System.Net.Http/WinHttpHandler.xml
ManickaP Nov 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 107 additions & 114 deletions xml/System.Net.Http/WinHttpHandler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,16 +36,16 @@
<summary>
Handles messages based on the WinHTTP interface of Windows. This class is intended for use in server environments.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
<format type="text/markdown"><![CDATA[

## Remarks

<xref:System.Net.Http.WinHttpHandler> is similar to other existing classes such as <xref:System.Net.Http.HttpClientHandler>. <xref:System.Net.Http.WinHttpHandler> provides a handler underneath an <xref:System.Net.Http.HttpClient> instance and is used to send HTTP requests out to a server and receive server responses. The <xref:System.Net.Http.WinHttpHandler> implementation supports HTTP versions up to HTTP/2.
<xref:System.Net.Http.WinHttpHandler> is designed to be used primarily in server environments by ASP.NET Core and other .NET applications that communicate with HTTP servers. <xref:System.Net.Http.WinHttpHandler> also provides developers with more granular control over the application's HTTP communication than the <xref:System.Net.Http.HttpClientHandler> class. This allows developers to implement more advanced HTTP scenarios or modify system defaults (for example, proxy settings, timeouts, and server SSL certificate validation).
<xref:System.Net.Http.WinHttpHandler> is not intended to be a replacement for <xref:System.Net.Http.HttpClientHandler>. Instead, it's a more advanced version that's provided for scenarios where <xref:System.Net.Http.HttpClientHandler> is insufficient. <xref:System.Net.Http.WinHttpHandler> is implemented as a thin wrapper on the WinHTTP interface of Windows and is only supported on Windows systems.
<xref:System.Net.Http.WinHttpHandler> is similar to other existing classes such as <xref:System.Net.Http.HttpClientHandler>. <xref:System.Net.Http.WinHttpHandler> provides a handler underneath an <xref:System.Net.Http.HttpClient> instance and is used to send HTTP requests out to a server and receive server responses. The <xref:System.Net.Http.WinHttpHandler> implementation supports HTTP versions up to HTTP/2.

<xref:System.Net.Http.WinHttpHandler> provides developers with more granular control over the application's HTTP communication than the <xref:System.Net.Http.HttpClientHandler> class. This allows developers to implement more advanced HTTP scenarios or modify system defaults (for example, proxy settings, timeouts, and server SSL certificate validation).

<xref:System.Net.Http.WinHttpHandler> is not intended to be a replacement for <xref:System.Net.Http.HttpClientHandler>. Instead, it's a more advanced version that's provided for scenarios where <xref:System.Net.Http.HttpClientHandler> is insufficient. <xref:System.Net.Http.WinHttpHandler> is implemented as a thin wrapper on the WinHTTP interface of Windows and is only supported on Windows systems.

When using a chain of multiple handlers, <xref:System.Net.Http.WinHttpHandler> should be at the bottom of the chain.

This class is also available for use in Desktop apps by installing it as a NuGet package. For more information, see [System.Net.Http.WinHttpHandler NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/).
Expand Down Expand Up @@ -98,11 +98,11 @@ Starting in .NET 5, <xref:System.Net.Http.WinHttpHandler> is no longer included
<summary>Gets or sets the type of decompression method used by the handler for automatic decompression of the HTTP content response.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is `GZip | Deflate`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is `None`.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -130,12 +130,12 @@ Starting in .NET 5, <xref:System.Net.Http.WinHttpHandler> is no longer included
<value>
<see langword="true" /> to follow HTTP redirection responses; otherwise, <see langword="false" />. The default is <see langword="true" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
<format type="text/markdown"><![CDATA[

## Remarks

When this property is set to `true`, all HTTP redirect responses from the server will be followed automatically except if they are redirecting from an HTTPS endpoint to an HTTP endpoint.
When this property is set to `true`, all HTTP redirect responses from the server will be followed automatically except if they are redirecting from an HTTPS endpoint to an HTTP endpoint.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -187,11 +187,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets a value that indicates if the certificate is automatically picked from the certificate store or if the caller is allowed to pass in a specific client certificate.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is <xref:System.Net.Http.ClientCertificateOption.Manual?displayProperty=nameWithType>.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is <xref:System.Net.Http.ClientCertificateOption.Manual?displayProperty=nameWithType>.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -224,11 +224,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets a collection of client authentication SSL certificates that are used for client authentication by the handler if the <see cref="P:System.Net.Http.WinHttpHandler.ClientCertificateOption" /> property is set to <see langword="Manual" />.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is an empty collection.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is an empty collection.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -256,11 +256,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the managed cookie container object. This property is only used when the <see cref="P:System.Net.Http.WinHttpHandler.CookieUsePolicy" /> property is set to UseSpecifiedCookieContainer. Otherwise, the <see cref="M:System.Net.Http.WinHttpHandler.SendAsync(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method will throw an exception.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is `null`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is `null`.

]]></format>
</remarks>
</Docs>
Expand All @@ -287,11 +287,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets a value that indicates how cookies should be managed and used. Developers can choose to ignore cookies, allow the handler to automatically manage them or manually handle them using a <see cref="T:System.Net.CookieContainer" /> object.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default for this property is <xref:System.Net.Http.CookieUsePolicy.UseInternalCookieStoreOnly?displayProperty=nameWithType>. If this value is set to <xref:System.Net.Http.CookieUsePolicy.UseSpecifiedCookieContainer?displayProperty=nameWithType>, then a container object must be initialized and assigned to the <xref:System.Net.Http.WinHttpHandler.CookieContainer%2A> property. Otherwise, an exception will be thrown when trying to send a request.
<format type="text/markdown"><![CDATA[

## Remarks
The default for this property is <xref:System.Net.Http.CookieUsePolicy.UseInternalCookieStoreOnly?displayProperty=nameWithType>. If this value is set to <xref:System.Net.Http.CookieUsePolicy.UseSpecifiedCookieContainer?displayProperty=nameWithType>, then a container object must be initialized and assigned to the <xref:System.Net.Http.WinHttpHandler.CookieContainer%2A> property. Otherwise, an exception will be thrown when trying to send a request.

]]></format>
</remarks>
</Docs>
Expand All @@ -316,16 +316,9 @@ When this property is set to `true`, all HTTP redirect responses from the server
<ReturnType>System.Net.ICredentials</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the credentials used to authenticate the user to an authenticating proxy.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is <xref:System.Net.CredentialCache.DefaultCredentials?displayProperty=nameWithType>.

]]></format>
</remarks>
<summary>When the default (system) proxy is used, gets or sets the credentials used to submit to the default proxy server for authentication.</summary>
<value>The credentials used to authenticate the user to an authenticating proxy.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
<MemberGroup MemberName="Dispose">
Expand Down Expand Up @@ -412,11 +405,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the maximum number of allowed HTTP redirects.</summary>
<value>The maximum number of allowed HTTP redirects.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is 50. This value only applies if <xref:System.Net.Http.WinHttpHandler.AutomaticRedirection%2A> is set to `true`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is 50. This value only applies if <xref:System.Net.Http.WinHttpHandler.AutomaticRedirection%2A> is set to `true`.

]]></format>
</remarks>
</Docs>
Expand All @@ -443,11 +436,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the maximum number of TCP connections allowed to a single server.</summary>
<value>The maximum number of TCP connections allowed to a single server.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is `int.MaxValue`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is `int.MaxValue`.

]]></format>
</remarks>
</Docs>
Expand All @@ -474,11 +467,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the maximum amount of data that can be drained from responses in bytes.</summary>
<value>The maximum amount of data that can be drained from responses in bytes.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is 65536.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is 65536.

]]></format>
</remarks>
</Docs>
Expand All @@ -502,14 +495,14 @@ When this property is set to `true`, all HTTP redirect responses from the server
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the maximum size of the header portion from the server response in bytes.</summary>
<value>The maximum size of the header portion from the server response in bytes.</value>
<summary>Gets or sets the maximum length, in kilobytes (1024 bytes), of the response headers.</summary>
<value>The maximum length, in kilobytes (1024 bytes), of the response headers.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This property protects the client from an unauthorized server attempting to stall the client by sending a response with an infinite amount of header data. The default value for this property is 65536.
<format type="text/markdown"><![CDATA[

## Remarks
This property protects the client from an unauthorized server attempting to stall the client by sending a response with an infinite amount of header data. The default value for this property is 64 KB (equivalent to 65536 bytes).

]]></format>
</remarks>
</Docs>
Expand All @@ -536,11 +529,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets a value that indicates whether the handler sends an Authorization header with the request.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is `false`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is `false`.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -598,11 +591,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the custom proxy when the <see cref="P:System.Net.Http.WinHttpHandler.WindowsProxyUsePolicy" /> property is set to use a custom proxy.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is `null`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is `null`.

]]></format>
</remarks>
</Docs>
Expand All @@ -629,11 +622,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the timeout for receiving the data portion of a response from the server.</summary>
<value>The timeout for receiving the data portion of a response from the server.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is 30 seconds.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is 30 seconds.

]]></format>
</remarks>
</Docs>
Expand All @@ -660,11 +653,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the timeout for receiving the headers of a response from the server.</summary>
<value>The timeout for receiving the headers of a response from the server.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is 30 seconds.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is 30 seconds.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -722,11 +715,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the timeout for sending a request.</summary>
<value>The timeout for sending a request.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is 30 seconds.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is 30 seconds.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -760,11 +753,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets a callback method to validate the server certificate. This callback is part of the SSL handshake.</summary>
<value>The callback should return <see langword="true" /> if the server certificate is considered valid and the request should be sent. Otherwise, return <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value is `null`. If this property is `null`, the server certificate is validated using standard well-known certificate authorities.
<format type="text/markdown"><![CDATA[

## Remarks
The default value is `null`. If this property is `null`, the server certificate is validated using standard well-known certificate authorities.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -792,11 +785,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the credentials to be used by the client to authenticate to the server.</summary>
<value>The credentials to be used by the client to authenticate to the server.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value for this property is `null`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value for this property is `null`.

]]></format>
</remarks>
</Docs>
Expand All @@ -823,11 +816,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
<summary>Gets or sets the collection of TLS/SSL protocols supported by the client.</summary>
<value>The collection of TLS/SSL protocols supported by the client.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value is `SslProtocols.Tls | SslProtocols.Tls11 | SslProtocols.Tls12`.
<format type="text/markdown"><![CDATA[

## Remarks
The default value is `None`, which is the recommended value. It allows the operating system to choose the best protocol to use, and to block protocols that are not secure. For more information, see <xref:System.Security.Authentication.SslProtocols>.

]]></format>
</remarks>
</Docs>
Expand Down Expand Up @@ -950,11 +943,11 @@ Only supported on Windows 10 version 2004 or newer.
<summary>Gets or sets the proxy setting. This property can be set to disable the proxy, use a custom proxy, or use the proxy settings of WinHTTP or WinInet on the machine.</summary>
<value>To be added.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default value of this property is the WinHTTP stack proxy settings.
<format type="text/markdown"><![CDATA[

## Remarks
The default value of this property is the WinHTTP stack proxy settings.

]]></format>
</remarks>
</Docs>
Expand Down