Skip to content

Commit b4df947

Browse files
ManickaPCarnaViire
ManickaP
and
CarnaViire
authored
Collected fixes for WinHttpHandler (dotnet#10638)
* Fix default value for AutomaticDecompression * Remove non-sensical sentence from summary * Fix MaxResponseHeadersLength * DefaultProxyCredentials * Fix docs about ssl protocols default * Remove remarks * Update xml/System.Net.Http/WinHttpHandler.xml Co-authored-by: Natalia Kondratyeva <knatalia@microsoft.com> --------- Co-authored-by: Natalia Kondratyeva <knatalia@microsoft.com>
1 parent 559ab03 commit b4df947

File tree

1 file changed

+107
-114
lines changed

1 file changed

+107
-114
lines changed

‎xml/System.Net.Http/WinHttpHandler.xml

Lines changed: 107 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,16 @@
3636
<summary>
3737
Handles messages based on the WinHTTP interface of Windows. This class is intended for use in server environments.</summary>
3838
<remarks>
39-
<format type="text/markdown"><![CDATA[
40-
39+
<format type="text/markdown"><![CDATA[
40+
4141
## Remarks
4242
43-
<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.
44-
45-
<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).
46-
47-
<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.
48-
43+
<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.
44+
45+
<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).
46+
47+
<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.
48+
4949
When using a chain of multiple handlers, <xref:System.Net.Http.WinHttpHandler> should be at the bottom of the chain.
5050
5151
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/).
@@ -98,11 +98,11 @@ Starting in .NET 5, <xref:System.Net.Http.WinHttpHandler> is no longer included
9898
<summary>Gets or sets the type of decompression method used by the handler for automatic decompression of the HTTP content response.</summary>
9999
<value>To be added.</value>
100100
<remarks>
101-
<format type="text/markdown"><![CDATA[
102-
103-
## Remarks
104-
The default value for this property is `GZip | Deflate`.
105-
101+
<format type="text/markdown"><![CDATA[
102+
103+
## Remarks
104+
The default value for this property is `None`.
105+
106106
]]></format>
107107
</remarks>
108108
</Docs>
@@ -130,12 +130,12 @@ Starting in .NET 5, <xref:System.Net.Http.WinHttpHandler> is no longer included
130130
<value>
131131
<see langword="true" /> to follow HTTP redirection responses; otherwise, <see langword="false" />. The default is <see langword="true" />.</value>
132132
<remarks>
133-
<format type="text/markdown"><![CDATA[
134-
133+
<format type="text/markdown"><![CDATA[
134+
135135
## Remarks
136136
137-
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.
138-
137+
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.
138+
139139
]]></format>
140140
</remarks>
141141
</Docs>
@@ -187,11 +187,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
187187
<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>
188188
<value>To be added.</value>
189189
<remarks>
190-
<format type="text/markdown"><![CDATA[
191-
192-
## Remarks
193-
The default value for this property is <xref:System.Net.Http.ClientCertificateOption.Manual?displayProperty=nameWithType>.
194-
190+
<format type="text/markdown"><![CDATA[
191+
192+
## Remarks
193+
The default value for this property is <xref:System.Net.Http.ClientCertificateOption.Manual?displayProperty=nameWithType>.
194+
195195
]]></format>
196196
</remarks>
197197
</Docs>
@@ -224,11 +224,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
224224
<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>
225225
<value>To be added.</value>
226226
<remarks>
227-
<format type="text/markdown"><![CDATA[
228-
229-
## Remarks
230-
The default value for this property is an empty collection.
231-
227+
<format type="text/markdown"><![CDATA[
228+
229+
## Remarks
230+
The default value for this property is an empty collection.
231+
232232
]]></format>
233233
</remarks>
234234
</Docs>
@@ -256,11 +256,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
256256
<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>
257257
<value>To be added.</value>
258258
<remarks>
259-
<format type="text/markdown"><![CDATA[
260-
261-
## Remarks
262-
The default value for this property is `null`.
263-
259+
<format type="text/markdown"><![CDATA[
260+
261+
## Remarks
262+
The default value for this property is `null`.
263+
264264
]]></format>
265265
</remarks>
266266
</Docs>
@@ -287,11 +287,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
287287
<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>
288288
<value>To be added.</value>
289289
<remarks>
290-
<format type="text/markdown"><![CDATA[
291-
292-
## Remarks
293-
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.
294-
290+
<format type="text/markdown"><![CDATA[
291+
292+
## Remarks
293+
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.
294+
295295
]]></format>
296296
</remarks>
297297
</Docs>
@@ -316,16 +316,9 @@ When this property is set to `true`, all HTTP redirect responses from the server
316316
<ReturnType>System.Net.ICredentials</ReturnType>
317317
</ReturnValue>
318318
<Docs>
319-
<summary>Gets or sets the credentials used to authenticate the user to an authenticating proxy.</summary>
320-
<value>To be added.</value>
321-
<remarks>
322-
<format type="text/markdown"><![CDATA[
323-
324-
## Remarks
325-
The default value for this property is <xref:System.Net.CredentialCache.DefaultCredentials?displayProperty=nameWithType>.
326-
327-
]]></format>
328-
</remarks>
319+
<summary>When the default (system) proxy is used, gets or sets the credentials used to submit to the default proxy server for authentication.</summary>
320+
<value>The credentials used to authenticate the user to an authenticating proxy.</value>
321+
<remarks>To be added.</remarks>
329322
</Docs>
330323
</Member>
331324
<MemberGroup MemberName="Dispose">
@@ -412,11 +405,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
412405
<summary>Gets or sets the maximum number of allowed HTTP redirects.</summary>
413406
<value>The maximum number of allowed HTTP redirects.</value>
414407
<remarks>
415-
<format type="text/markdown"><![CDATA[
416-
417-
## Remarks
418-
The default value for this property is 50. This value only applies if <xref:System.Net.Http.WinHttpHandler.AutomaticRedirection%2A> is set to `true`.
419-
408+
<format type="text/markdown"><![CDATA[
409+
410+
## Remarks
411+
The default value for this property is 50. This value only applies if <xref:System.Net.Http.WinHttpHandler.AutomaticRedirection%2A> is set to `true`.
412+
420413
]]></format>
421414
</remarks>
422415
</Docs>
@@ -443,11 +436,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
443436
<summary>Gets or sets the maximum number of TCP connections allowed to a single server.</summary>
444437
<value>The maximum number of TCP connections allowed to a single server.</value>
445438
<remarks>
446-
<format type="text/markdown"><![CDATA[
447-
448-
## Remarks
449-
The default value for this property is `int.MaxValue`.
450-
439+
<format type="text/markdown"><![CDATA[
440+
441+
## Remarks
442+
The default value for this property is `int.MaxValue`.
443+
451444
]]></format>
452445
</remarks>
453446
</Docs>
@@ -474,11 +467,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
474467
<summary>Gets or sets the maximum amount of data that can be drained from responses in bytes.</summary>
475468
<value>The maximum amount of data that can be drained from responses in bytes.</value>
476469
<remarks>
477-
<format type="text/markdown"><![CDATA[
478-
479-
## Remarks
480-
The default value for this property is 65536.
481-
470+
<format type="text/markdown"><![CDATA[
471+
472+
## Remarks
473+
The default value for this property is 65536.
474+
482475
]]></format>
483476
</remarks>
484477
</Docs>
@@ -502,14 +495,14 @@ When this property is set to `true`, all HTTP redirect responses from the server
502495
<ReturnType>System.Int32</ReturnType>
503496
</ReturnValue>
504497
<Docs>
505-
<summary>Gets or sets the maximum size of the header portion from the server response in bytes.</summary>
506-
<value>The maximum size of the header portion from the server response in bytes.</value>
498+
<summary>Gets or sets the maximum length, in kilobytes (1024 bytes), of the response headers.</summary>
499+
<value>The maximum length, in kilobytes (1024 bytes), of the response headers.</value>
507500
<remarks>
508-
<format type="text/markdown"><![CDATA[
509-
510-
## Remarks
511-
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.
512-
501+
<format type="text/markdown"><![CDATA[
502+
503+
## Remarks
504+
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).
505+
513506
]]></format>
514507
</remarks>
515508
</Docs>
@@ -536,11 +529,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
536529
<summary>Gets or sets a value that indicates whether the handler sends an Authorization header with the request.</summary>
537530
<value>To be added.</value>
538531
<remarks>
539-
<format type="text/markdown"><![CDATA[
540-
541-
## Remarks
542-
The default value for this property is `false`.
543-
532+
<format type="text/markdown"><![CDATA[
533+
534+
## Remarks
535+
The default value for this property is `false`.
536+
544537
]]></format>
545538
</remarks>
546539
</Docs>
@@ -598,11 +591,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
598591
<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>
599592
<value>To be added.</value>
600593
<remarks>
601-
<format type="text/markdown"><![CDATA[
602-
603-
## Remarks
604-
The default value for this property is `null`.
605-
594+
<format type="text/markdown"><![CDATA[
595+
596+
## Remarks
597+
The default value for this property is `null`.
598+
606599
]]></format>
607600
</remarks>
608601
</Docs>
@@ -629,11 +622,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
629622
<summary>Gets or sets the timeout for receiving the data portion of a response from the server.</summary>
630623
<value>The timeout for receiving the data portion of a response from the server.</value>
631624
<remarks>
632-
<format type="text/markdown"><![CDATA[
633-
634-
## Remarks
635-
The default value for this property is 30 seconds.
636-
625+
<format type="text/markdown"><![CDATA[
626+
627+
## Remarks
628+
The default value for this property is 30 seconds.
629+
637630
]]></format>
638631
</remarks>
639632
</Docs>
@@ -660,11 +653,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
660653
<summary>Gets or sets the timeout for receiving the headers of a response from the server.</summary>
661654
<value>The timeout for receiving the headers of a response from the server.</value>
662655
<remarks>
663-
<format type="text/markdown"><![CDATA[
664-
665-
## Remarks
666-
The default value for this property is 30 seconds.
667-
656+
<format type="text/markdown"><![CDATA[
657+
658+
## Remarks
659+
The default value for this property is 30 seconds.
660+
668661
]]></format>
669662
</remarks>
670663
</Docs>
@@ -722,11 +715,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
722715
<summary>Gets or sets the timeout for sending a request.</summary>
723716
<value>The timeout for sending a request.</value>
724717
<remarks>
725-
<format type="text/markdown"><![CDATA[
726-
727-
## Remarks
728-
The default value for this property is 30 seconds.
729-
718+
<format type="text/markdown"><![CDATA[
719+
720+
## Remarks
721+
The default value for this property is 30 seconds.
722+
730723
]]></format>
731724
</remarks>
732725
</Docs>
@@ -760,11 +753,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
760753
<summary>Gets or sets a callback method to validate the server certificate. This callback is part of the SSL handshake.</summary>
761754
<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>
762755
<remarks>
763-
<format type="text/markdown"><![CDATA[
764-
765-
## Remarks
766-
The default value is `null`. If this property is `null`, the server certificate is validated using standard well-known certificate authorities.
767-
756+
<format type="text/markdown"><![CDATA[
757+
758+
## Remarks
759+
The default value is `null`. If this property is `null`, the server certificate is validated using standard well-known certificate authorities.
760+
768761
]]></format>
769762
</remarks>
770763
</Docs>
@@ -792,11 +785,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
792785
<summary>Gets or sets the credentials to be used by the client to authenticate to the server.</summary>
793786
<value>The credentials to be used by the client to authenticate to the server.</value>
794787
<remarks>
795-
<format type="text/markdown"><![CDATA[
796-
797-
## Remarks
798-
The default value for this property is `null`.
799-
788+
<format type="text/markdown"><![CDATA[
789+
790+
## Remarks
791+
The default value for this property is `null`.
792+
800793
]]></format>
801794
</remarks>
802795
</Docs>
@@ -823,11 +816,11 @@ When this property is set to `true`, all HTTP redirect responses from the server
823816
<summary>Gets or sets the collection of TLS/SSL protocols supported by the client.</summary>
824817
<value>The collection of TLS/SSL protocols supported by the client.</value>
825818
<remarks>
826-
<format type="text/markdown"><![CDATA[
827-
828-
## Remarks
829-
The default value is `SslProtocols.Tls | SslProtocols.Tls11 | SslProtocols.Tls12`.
830-
819+
<format type="text/markdown"><![CDATA[
820+
821+
## Remarks
822+
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>.
823+
831824
]]></format>
832825
</remarks>
833826
</Docs>
@@ -950,11 +943,11 @@ Only supported on Windows 10 version 2004 or newer.
950943
<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>
951944
<value>To be added.</value>
952945
<remarks>
953-
<format type="text/markdown"><![CDATA[
954-
955-
## Remarks
956-
The default value of this property is the WinHTTP stack proxy settings.
957-
946+
<format type="text/markdown"><![CDATA[
947+
948+
## Remarks
949+
The default value of this property is the WinHTTP stack proxy settings.
950+
958951
]]></format>
959952
</remarks>
960953
</Docs>

0 commit comments

Comments
 (0)