8000 SocketsHttpHandler - update documentation (#4290) · dotnet/dotnet-api-docs@2b21ba6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2b21ba6

Browse files
Jan JahodamairawJan Jahodakarelz
authored
SocketsHttpHandler - update documentation (#4290)
* Add ctor doc * AllowAutoRedirect doc * Connect timeout doc * Credentials doc * SocketsHttpHandler.Expect100ContinueTimeout doc * Update xml/System.Net.Http/SocketsHttpHandler.xml Co-authored-by: Maira Wenzel <mairaw@microsoft.com> * Apply suggestions from code review Co-authored-by: Karel Zikmund <karelz@microsoft.com> Co-authored-by: Maira Wenzel <mairaw@microsoft.com> * Documentation * Update xml/System.Net.Http/SocketsHttpHandler.xml Co-authored-by: Maira Wenzel <mairaw@microsoft.com> * RP comments Co-authored-by: Maira Wenzel <mairaw@microsoft.com> Co-authored-by: Jan Jahoda <jajahoda@.microsoft.com> Co-authored-by: Karel Zikmund <karelz@microsoft.com>
1 parent 0571618 commit 2b21ba6

File tree

1 file changed

+58
-21
lines changed

1 file changed

+58
-21
lines changed

‎xml/System.Net.Http/SocketsHttpHandler.xml

Lines changed: 58 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ If this change is undesirable, you can configure your application to use the old
7070
</AssemblyInfo>
7171
<Parameters />
7272
<Docs>
73-
<summary>To be added.</summary>
73+
<summary>Creates an instance of a <see cref="T:System.Net.Http.SocketsHttpHandler" /> class.</summary>
7474
<remarks>To be added.</remarks>
7575
</Docs>
7676
</Member>
@@ -92,9 +92,25 @@ If this change is undesirable, you can configure your application to use the old
9292
<ReturnType>System.Boolean</ReturnType>
9393
</ReturnValue>
9494
<Docs>
95-
<summary>To be added.</summary>
96-
<value>To be added.</value>
97-
<remarks>To be added.</remarks>
95+
<summary>Gets or sets a value that indicates whether the handler should follow redirection responses.</summary>
96+
<value>
97+
<see langword="true" /> if the handler should follow redirection responses; otherwise <see langword="false" />. The default value is <see langword="true" />.
98+
</value>
99+
<remarks>
100+
<format type="text/markdown"><![CDATA[
101+
102+
## Remarks
103+
Set <xref:System.Net.Http.SocketsHttpHandler.AllowAutoRedirect%2A> to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the <xref:System.Net.Http.SocketsHttpHandler.MaxAutomaticRedirections%2A> property.
104+
105+
If <xref:System.Net.Http.SocketsHttpHandler.AllowAutoRedirect%2A> is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application.
106+
107+
The Authorization header is cleared on auto-redirects and the handler automatically tries to re-authenticate to the redirected location. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module.
108+
109+
> [!NOTE]
110+
> The handler never follows a redirection from HTTPS to HTTP even if <xref:System.Net.Http.SocketsHttpHandler.AllowAutoRedirect%2A> is set to `true`.
111+
112+
]]></format>
113+
</remarks>
98114
</Docs>
99115
</Member>
100116
<Member MemberName="AutomaticDecompression">
@@ -138,8 +154,8 @@ If this change is undesirable, you can configure your application to use the old
138154
<ReturnType>System.TimeSpan</ReturnType>
139155
</ReturnValue>
140156
<Docs>
141-
<summary>To be added.</summary>
142-
<value>To be added.</value>
157+
<summary>Gets or sets the timespan to wait before the connection establishing times out.</summary>
158+
<value>The timespan to wait before the connection establishing times out. The default value is <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</value>
143159
<remarks>To be added.</remarks>
144160
</Docs>
145161
</Member>
@@ -184,8 +200,8 @@ If this change is undesirable, you can configure your application to use the old
184200
<ReturnType>System.Net.ICredentials</ReturnType>
185201
</ReturnValue>
186202
<Docs>
187-
<summary>To be added.</summary>
188-
<value>To be added.</value>
203+
<summary>Gets or sets authentication information used by this handler.</summary>
204+
<value>The authentication credentials associated with the handler. The default value is <see langword="null" />.</value>
189205
<remarks>To be added.</remarks>
190206
</Docs>
191207
</Member>
@@ -262,9 +278,15 @@ The default proxy is used only when <xref:System.Net.Http.SocketsHttpHandler.Use
262278
<ReturnType>System.TimeSpan</ReturnType>
263279
</ReturnValue>
264280
<Docs>
265-
<summary>To be added.</summary>
266-
<value>To be added.</value>
267-
<remarks>To be added.</remarks>
281+
<summary>Gets or sets the time-out value for server HTTP 100 Continue response.</summary>
282+
<value>The timespan to wait for the HTTP 100 Continue. The default value is 1 second.</value>
283+
<remarks>
284+
<format type="text/markdown"><![CDATA[
285+
286+
## Remarks
287+
When request contain `Expect: 100-continue` header the server should respond HTTP status `100 Continue` before the client sends the body. <xref:System.Net.Http.SocketsHttpHandler.Expect100ContinueTimeout%2A?displayProperty=nameWithType> define the timeout for the `100 Continue` server response.
288+
289+
]]></format></remarks>
268290
</Docs>
269291
</Member>
270292
<Member MemberName="MaxAutomaticRedirections">
@@ -413,9 +435,18 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
413435
<ReturnType>System.TimeSpan</ReturnType>
414436
</ReturnValue>
415437
<Docs>
416-
<summary>To be added.</summary>
417-
<value>To be added.</value>
418-
<remarks>To be added.</remarks>
438+
<summary>Gets or sets how long a connection can be the pool to be considered reusable.</summary>
439+
<value>The maximum time for a connection to be in the pool. The default value for this property is <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</value>
440+
<remarks> <format type="text/markdown"><![CDATA[
441+
442+
## Remarks
443+
This property define maximal connection lifetime in the pool regardles the connection is idle or active. The connection is reestablished periodically to reflect the DNS or other network changes.
444+
445+
If the connection endpoint is not the Doamin name but the IP address, the value can be <xref:System.Threading.Timeout.InfiniteTimeSpan>.
446+
447+
]]></format>
448+
</remarks>
449+
<exception cref="T:System.ArgumentOutOfRangeException">The value specified is less than <see cref="F:System.TimeSpan.Zero" /> or is equal to <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</exception>
419450
</Docs>
420451
</Member>
421452
<Member MemberName="PreAuthenticate">
@@ -506,9 +537,15 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
506537
<ReturnType>System.TimeSpan</ReturnType>
507538
</ReturnValue>
508539
<Docs>
509-
<summary>To be added.</summary>
510-
<value>To be added.</value>
511-
<remarks>To be added.</remarks>
540+
<summary>Gets or sets the timespan to wait for data to be drained from responses.</summary>
541+
<value>The timespan to wait for data to be drained from responses.</value>
542+
<remarks>
543+
<format type="text/markdown"><![CDATA[
544+
545+
Draining occurs when a request is cancelled or a response is disposed prior to fully reading the content. If the time exceeds the value, the connection will be closed rather than reused.
546+
547+
]]></format>
548+
</remarks>
512549
</Docs>
513550
</Member>
514551
<Member MemberName="SendAsync">
@@ -581,8 +618,8 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
581618
<ReturnType>System.Boolean</ReturnType>
582619
</ReturnValue>
583620
<Docs>
584-
<summary>To be added.</summary>
585-
<value>To be added.</value>
621+
<summary>Gets or sets a value that indicates whether the handler should use cookies.</summary>
622+
<value>A value that indicates whether the handler should use cookies.</value>
586623
<remarks>To be added.</remarks>
587624
</Docs>
588625
</Member>
@@ -604,8 +641,8 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
604641
<ReturnType>System.Boolean</ReturnType>
605642
</ReturnValue>
606643
<Docs>
607-
<summary>To be added.</summary>
608-
<value>To be added.</value>
644+
<summary>Gets or sets a value that indicates whether the handler should use a proxy.</summary>
645+
<value>A value that indicates whether the handler should use a proxy.</value>
609646
<remarks>To be added.</remarks>
610647
</Docs>
611648
</Member>

0 commit comments

Comments
 (0)
0