From d7800cfbf9d5239170a5b5178c7d60093eded90f Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Thu, 12 Mar 2020 17:44:44 -0700 Subject: [PATCH 01/12] Updated HttpClient main topic to address user feedback from issues. --- xml/System.Net.Http/HttpClient.xml | 113 +++++++++++++++++++++-------- 1 file changed, 84 insertions(+), 29 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 4b0c172f078..406ad2d8af7 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -30,34 +30,10 @@ ## Remarks The class instance acts as a session to send HTTP requests. An instance is a collection of settings applied to all requests executed by that instance. In addition, every instance uses its own connection pool, isolating its requests from requests executed by other instances. - - The also acts as a base class for more specific HTTP clients. An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Derived classes should not override the virtual methods on the class. Instead, use a constructor overload that accepts to configure any pre- or post-request processing instead. - - By default on .NET Framework and Mono, is used to send requests to the server. This behavior can be modified by specifying a different channel in one of the constructor overloads taking a instance as parameter. If features like authentication or caching are required, can be used to configure settings and the instance can be passed to the constructor. The returned handler can be passed to one of the constructor overloads taking a parameter. - - If an app using and related classes in the namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance. - - The following methods are thread safe: - -1. - -2. - -3. - -4. - -5. - -6. - -7. - -8. - -9. - - is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly. + + ### Instancing + + is intended to be instantiated once and re-used throughout the life of an application. HttpClient is designed to pool connections, and re-use a connection across multiple requests. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly. ```csharp public class GoodController : ApiController @@ -82,6 +58,13 @@ public class GoodController : ApiController End Sub End Class ``` +Additional options can be configured by passing in a (or in .NET Core 2.1 or later) as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if the connection properties need to be changed. + +### Derivation + + The also acts as a base class for more specific HTTP clients. An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Derived classes should not override the virtual methods on the class. Instead, use a constructor overload that accepts to configure any pre- or post-request processing instead. + +### Transports The is a high-level API that wraps the lower-level functionality available on each platform where it runs. @@ -104,7 +87,11 @@ On each platform, tries to use the best availa Users can also configure a specific transport for by invoking the constructor that takes an . -### HttpClient and .NET Core +#### .NET Framework & Mono + + By default on .NET Framework and Mono, is used to send requests to the server. This behavior can be modified by specifying a different channel in one of the constructor overloads taking a instance as parameter. If features like authentication or caching are required, can be used to configure settings and the instance can be passed to the constructor. The returned handler can be passed to one of the constructor overloads taking a parameter. + +#### .NET Core Starting with .NET Core 2.1, the class instead of `HttpClientHandler` provides the implementation used by higher-level HTTP networking classes such as `HttpClient`. The use of offers a number of advantages: @@ -137,6 +124,74 @@ If this change is undesirable, you can configure your application to use the old - By defining an environment variable named `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` and setting it to either `false` or 0. +### Connection Pooling + +HttpClient will pool HTTP connections where possible, and use them for more than one request. This can have a significant performance benefit, especially for HTTPS requests, as the connection handshake is only done once. + +Connection pool properties can be configured on a or passed in during construction, including , and . + +Todo: Disposing of the HttpClient instance will close the open connections and cancel any pending requests. + +### Buffering & Request lifetime + +By default, HttpClient methods (except ) will buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: + +* The succeds and returns a result +* The is reached, in which case the will be cancelled +* The passable to some method overloads is fired +* is called +* The HttpClient is disposed + +The buffering behavior can be changed on a per request basis using the HttpCompletionOption parameter available on some method overloads. This can be used to specify if the should be considered complete after reading just the response headers, or having read and buffered the response content. + +If an app using and related classes in the namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance. + +### Thread Safety + + The following methods are thread safe: + +1. + +2. + +3. + +4. + +5. + +6. + +7. + +8. + +9. + +### Proxies + +By deafult HttpClient will read proxy configuration from environment variables or user / system settings depending on the platform being used. This can be changed by passing a or to, in order of precedence: + +* The property on a HttpClientHandler passed in during HttpClient construction +* The static property (affects all instanes) + +The proxy can be disabled using . The default configuration for Windows users is to try and detect a proxy using network discovery which can be slow. For high througput applications where its known that a proxy is not required, the proxy should be disabled. + +### Timeouts + +HttpClient.Timeout can be used to set a default timeout for all Http requests from the HttpClient instance. The timeout only applies to the xxxAsync methods that cause a request/response to be initiated. If the timeout is reached, the for that request will be cancelled. + +Some Additional timeouts can be set if you construct the HttpClient passing in a instance: + +| **Property** | **Description**| +| ------------ | -------------- | +| | Specifies a timeout that is used when a request requires a new TCP connection to be created. If the timout occurs the request is cancelled. | +| | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, it is immediately closed, otherwise at the end of the current request. | +| | If a connection in the connection pool is idle for this long the connection will be closed. | +| | If request has an "Expect: 100-continue" header, it will delay sending the body until the timeout or a "100-continue" response has been recieved. | + +HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be requiried when replacing the connection. + ## Examples [!code-csharp[System.Net.Http.HttpClient#1](~/samples/snippets/csharp/VS_Snippets_Misc/system.net.http.httpclient/cs/source.cs#1)] [!code-vb[System.Net.Http.HttpClient#1](~/samples/snippets/visualbasic/VS_Snippets_Misc/system.net.http.httpclient/vb/source.vb#1)] From d48d699b3451ac2ea189db57c3fbf093d1528eb7 Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Fri, 13 Mar 2020 10:47:49 -0700 Subject: [PATCH 02/12] fixed xrefs --- xml/System.Net.Http/HttpClient.xml | 32 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 406ad2d8af7..8dd035f3056 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -58,7 +58,7 @@ public class GoodController : ApiController End Sub End Class ``` -Additional options can be configured by passing in a (or in .NET Core 2.1 or later) as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if the connection properties need to be changed. +Additional options can be configured by passing in a (or in .NET Core 2.1 or later) as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if the connection properties need to be changed. ### Derivation @@ -128,18 +128,18 @@ If this change is undesirable, you can configure your application to use the old HttpClient will pool HTTP connections where possible, and use them for more than one request. This can have a significant performance benefit, especially for HTTPS requests, as the connection handshake is only done once. -Connection pool properties can be configured on a or passed in during construction, including , and . +Connection pool properties can be configured on a or passed in during construction, including , and . Todo: Disposing of the HttpClient instance will close the open connections and cancel any pending requests. ### Buffering & Request lifetime -By default, HttpClient methods (except ) will buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: +By default, HttpClient methods (except ) will buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: * The succeds and returns a result -* The is reached, in which case the will be cancelled -* The passable to some method overloads is fired -* is called +* The is reached, in which case the will be cancelled +* The passable to some method overloads is fired +* is called * The HttpClient is disposed The buffering behavior can be changed on a per request basis using the HttpCompletionOption parameter available on some method overloads. This can be used to specify if the should be considered complete after reading just the response headers, or having read and buffered the response content. @@ -170,27 +170,27 @@ If an app using and related classes in the or to, in order of precedence: +By deafult HttpClient will read proxy configuration from environment variables or user / system settings depending on the platform being used. This can be changed by passing a or to, in order of precedence: -* The property on a HttpClientHandler passed in during HttpClient construction -* The static property (affects all instanes) +* The property on a HttpClientHandler passed in during HttpClient construction +* The static property (affects all instanes) -The proxy can be disabled using . The default configuration for Windows users is to try and detect a proxy using network discovery which can be slow. For high througput applications where its known that a proxy is not required, the proxy should be disabled. +The proxy can be disabled using . The default configuration for Windows users is to try and detect a proxy using network discovery which can be slow. For high througput applications where its known that a proxy is not required, the proxy should be disabled. ### Timeouts HttpClient.Timeout can be used to set a default timeout for all Http requests from the HttpClient instance. The timeout only applies to the xxxAsync methods that cause a request/response to be initiated. If the timeout is reached, the for that request will be cancelled. -Some Additional timeouts can be set if you construct the HttpClient passing in a instance: +Some Additional timeouts can be set if you construct the HttpClient passing in a instance: | **Property** | **Description**| | ------------ | -------------- | -| | Specifies a timeout that is used when a request requires a new TCP connection to be created. If the timout occurs the request is cancelled. | -| | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, it is immediately closed, otherwise at the end of the current request. | -| | If a connection in the connection pool is idle for this long the connection will be closed. | -| | If request has an "Expect: 100-continue" header, it will delay sending the body until the timeout or a "100-continue" response has been recieved. | +| | Specifies a timeout that is used when a request requires a new TCP connection to be created. If the timout occurs the request is cancelled. | +| | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, it is immediately closed, otherwise at the end of the current request. | +| | If a connection in the connection pool is idle for this long the connection will be closed. | +| | If request has an "Expect: 100-continue" header, it will delay sending the body until the timeout or a "100-continue" response has been recieved. | -HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be requiried when replacing the connection. +HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be requiried when replacing the connection. ## Examples [!code-csharp[System.Net.Http.HttpClient#1](~/samples/snippets/csharp/VS_Snippets_Misc/system.net.http.httpclient/cs/source.cs#1)] From 6394b415b2617472ac0b94aa9ac469e3e42d71f6 Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Wed, 22 Jul 2020 14:46:30 -0700 Subject: [PATCH 03/12] Update xml/System.Net.Http/HttpClient.xml Co-authored-by: Jan Jahoda --- xml/System.Net.Http/HttpClient.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 224cb692ac9..bfd5184e8f6 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -93,7 +93,7 @@ Users can also configure a specific transport for class instead of `HttpClientHandler` provides the implementation used by higher-level HTTP networking classes such as `HttpClient`. The use of offers a number of advantages: +Starting with .NET Core 2.1, the class instead of provides the implementation used by higher-level HTTP networking classes such as . The use of offers a number of advantages: - A significant performance improvement when compared with the previous implementation. From a03c45e418fb4020d950945ffac2ec68eb091832 Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Wed, 22 Jul 2020 14:48:17 -0700 Subject: [PATCH 04/12] Update xml/System.Net.Http/HttpClient.xml Co-authored-by: Jan Jahoda --- xml/System.Net.Http/HttpClient.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index bfd5184e8f6..f2e2d7871e0 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -134,7 +134,7 @@ Todo: Disposing of the HttpClient instance will close the open connections and c ### Buffering & Request lifetime -By default, HttpClient methods (except ) will buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: +By default, HttpClient methods (except ) will buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: * The succeds and returns a result * The is reached, in which case the will be cancelled From 5603ab5493e3055197c5e6b8019af66b33b12073 Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Wed, 22 Jul 2020 14:48:30 -0700 Subject: [PATCH 05/12] Update xml/System.Net.Http/HttpClient.xml Co-authored-by: Jan Jahoda --- xml/System.Net.Http/HttpClient.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index f2e2d7871e0..13d4380952c 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -173,7 +173,7 @@ If an app using and related classes in the or to, in order of precedence: * The property on a HttpClientHandler passed in during HttpClient construction -* The static property (affects all instanes) +* The static property (affects all instanes) The proxy can be disabled using . The default configuration for Windows users is to try and detect a proxy using network discovery which can be slow. For high througput applications where its known that a proxy is not required, the proxy should be disabled. From ba473714a3319c973bd912a5409e58a43f3f1f48 Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Wed, 22 Jul 2020 14:49:08 -0700 Subject: [PATCH 06/12] Update xml/System.Net.Http/HttpClient.xml Co-authored-by: Cory Nelson --- xml/System.Net.Http/HttpClient.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 13d4380952c..0bdc09babab 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -188,7 +188,7 @@ Some Additional timeouts can be set if you construct the HttpClient passing in a | | Specifies a timeout that is used when a request requires a new TCP connection to be created. If the timout occurs the request is cancelled. | | | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, it is immediately closed, otherwise at the end of the current request. | | | If a connection in the connection pool is idle for this long the connection will be closed. | -| | If request has an "Expect: 100-continue" header, it will delay sending the body until the timeout or a "100-continue" response has been recieved. | +| | If request has an "Expect: 100-continue" header, it will delay sending content until the timeout or a "100-continue" response has been received. | HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be requiried when replacing the connection. From 50080b42764d4bf2b671b661889d72252fe3d8be Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Wed, 22 Jul 2020 14:49:43 -0700 Subject: [PATCH 07/12] Update xml/System.Net.Http/HttpClient.xml Co-authored-by: Cory Nelson --- xml/System.Net.Http/HttpClient.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 0bdc09babab..9acba402d7b 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -190,7 +190,7 @@ Some Additional timeouts can be set if you construct the HttpClient passing in a | | If a connection in the connection pool is idle for this long the connection will be closed. | | | If request has an "Expect: 100-continue" header, it will delay sending content until the timeout or a "100-continue" response has been received. | -HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be requiried when replacing the connection. +HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be required when replacing the connection. ## Examples [!code-csharp[System.Net.Http.HttpClient#1](~/samples/snippets/csharp/VS_Snippets_Misc/system.net.http.httpclient/cs/source.cs#1)] From 31dacf77b095c63cf0876476cd28897fd524af6b Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Mon, 29 Mar 2021 16:10:11 -0700 Subject: [PATCH 08/12] Update HttpClient.xml Merge conflict resolved, added in @stephentoub's changes --- xml/System.Net.Http/HttpClient.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 01e42f9af57..d03fad24264 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -62,7 +62,7 @@ public class GoodController : ApiController End Sub End Class ``` -Additional options can be configured by passing in a (or in .NET Core 2.1 or later) as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if the connection properties need to be changed. +Additional options can be configured by passing in a "handler", such as (or in .NET Core 2.1 or later) as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if the connection properties need to be changed. If different requests require different settings, this may also lead to an application having multiple instances, where each instance is configured appropriately, and then requests are issued on the relevant client. ### Derivation @@ -115,7 +115,7 @@ HttpClient will pool HTTP connections where possible, and use them for more than Connection pool properties can be configured on a or passed in during construction, including , and . -Todo: Disposing of the HttpClient instance will close the open connections and cancel any pending requests. +Disposing of the HttpClient instance will close the open connections and cancel any pending requests. ### Buffering & Request lifetime From 078435cfbf09b9a5cfc7b7d1bbab50681a5c3c36 Mon Sep 17 00:00:00 2001 From: Sam Spencer <54915162+samsp-msft@users.noreply.github.com> Date: Mon, 29 Mar 2021 16:14:50 -0700 Subject: [PATCH 09/12] Update HttpClient.xml --- xml/System.Net.Http/HttpClient.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index d03fad24264..a598fd20b38 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -93,7 +93,7 @@ Users can also configure a specific transport for is used to send requests to the server. This behavior can be modified by specifying a different channel in one of the constructor overloads taking a instance as parameter. If features like authentication or caching are required, can be used to configure settings and the instance can be passed to the constructor. The returned handler can be passed to one of the constructor overloads taking a parameter. + By default on .NET Framework and Mono, is used to send requests to the server. This behavior can be modified by specifying a different handler in one of the constructor overloads taking a instance as parameter. If features like authentication or caching are required, can be used to configure settings and the instance can be passed to the constructor. The returned handler can be passed to one of the constructor overloads taking a parameter. #### .NET Core @@ -508,7 +508,7 @@ The proxy server may be a hostname or IP address, optionally followed by a colon From 19922bc93b36a8a5a3a7a5ef997180876bae4359 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 20 May 2022 14:23:17 -0700 Subject: [PATCH 10/12] Apply suggestions from code review --- xml/System.Net.Http/HttpClient.xml | 70 +++++++++++++++--------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index a598fd20b38..89090971863 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -37,7 +37,7 @@ ### Instancing - is intended to be instantiated once and re-used throughout the life of an application. HttpClient is designed to pool connections, and re-use a connection across multiple requests. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly. + is intended to be instantiated once and reused throughout the life of an application. HttpClient is designed to pool connections and reuse a connection across multiple requests. If you instantiate an HttpClient class for every request, the number of sockets available under heavy loads will be exhausted. This exhaustion will result in errors. Following is an example that uses HttpClient correctly. ```csharp public class GoodController : ApiController @@ -62,11 +62,11 @@ public class GoodController : ApiController End Sub End Class ``` -Additional options can be configured by passing in a "handler", such as (or in .NET Core 2.1 or later) as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if the connection properties need to be changed. If different requests require different settings, this may also lead to an application having multiple instances, where each instance is configured appropriately, and then requests are issued on the relevant client. +You can configure additional options by passing in a "handler", such as (or in .NET Core 2.1 or later), as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if you need to change the connection properties. If different requests require different settings, this may also lead to an application having multiple instances, where each instance is configured appropriately, and then requests are issued on the relevant client. ### Derivation - The also acts as a base class for more specific HTTP clients. An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Derived classes should not override the virtual methods on the class. Instead, use a constructor overload that accepts to configure any pre- or post-request processing instead. + The also acts as a base class for more specific HTTP clients. An example would be a FacebookHttpClient that provides additional methods specific to a Facebook web service (for example, a `GetFriends` method). Derived classes should not override the virtual methods on the class. Instead, use a constructor overload that accepts to configure any pre-request or post-request processing. ### Transports @@ -93,7 +93,7 @@ Users can also configure a specific transport for is used to send requests to the server. This behavior can be modified by specifying a different handler in one of the constructor overloads taking a instance as parameter. If features like authentication or caching are required, can be used to configure settings and the instance can be passed to the constructor. The returned handler can be passed to one of the constructor overloads taking a parameter. + By default on .NET Framework and Mono, is used to send requests to the server. This behavior can be modified by specifying a different handler in one of the constructor overloads with an parameter. If you require features like authentication or caching, you can use to configure settings and the instance can be passed to the constructor. The returned handler can be passed to a constructor overload that has an parameter. #### .NET Core @@ -111,71 +111,71 @@ Certain aspects of 's behavior are customizable ### Connection Pooling -HttpClient will pool HTTP connections where possible, and use them for more than one request. This can have a significant performance benefit, especially for HTTPS requests, as the connection handshake is only done once. +HttpClient pools HTTP connections where possible and uses them for more than one request. This can have a significant performance benefit, especially for HTTPS requests, as the connection handshake is only done once. -Connection pool properties can be configured on a or passed in during construction, including , and . +Connection pool properties can be configured on a or passed in during construction, including , , and . -Disposing of the HttpClient instance will close the open connections and cancel any pending requests. +Disposing of the HttpClient instance closes the open connections and cancels any pending requests. -### Buffering & Request lifetime +### Buffering and request lifetime -By default, HttpClient methods (except ) will buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: +By default, HttpClient methods (except ) buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: -* The succeds and returns a result -* The is reached, in which case the will be cancelled -* The passable to some method overloads is fired -* is called -* The HttpClient is disposed +* The succeeds and returns a result. +* The is reached, in which case the will be cancelled. +* The passable to some method overloads is fired. +* is called. +* The HttpClient is disposed. -The buffering behavior can be changed on a per request basis using the HttpCompletionOption parameter available on some method overloads. This can be used to specify if the should be considered complete after reading just the response headers, or having read and buffered the response content. +You can change the buffering behavior on a per-request basis using the parameter available on some method overloads. This argument can be used to specify if the should be considered complete after reading just the response headers, or after reading and buffering the response content. -If an app using and related classes in the namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance. +If your app that uses and related classes in the namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If you use the default buffering, the client memory usage will get very large, potentially resulting in substantially reduced performance. ### Thread Safety The following methods are thread safe: -1. +- -2. +- -3. +- -4. +- -5. +- -6. +- -7. +- -8. +- -9. +- ### Proxies -By deafult HttpClient will read proxy configuration from environment variables or user / system settings depending on the platform being used. This can be changed by passing a or to, in order of precedence: +By default, HttpClient reads proxy configuration from environment variables or user/system settings, depending on the platform. You can change this behavior by passing a or to, in order of precedence: * The property on a HttpClientHandler passed in during HttpClient construction -* The static property (affects all instanes) +* The static property (affects all instances) -The proxy can be disabled using . The default configuration for Windows users is to try and detect a proxy using network discovery which can be slow. For high througput applications where its known that a proxy is not required, the proxy should be disabled. +You can disable the proxy using . The default configuration for Windows users is to try and detect a proxy using network discovery, which can be slow. For high throughput applications where it's known that a proxy isn't required, you should disable the proxy. ### Timeouts -HttpClient.Timeout can be used to set a default timeout for all Http requests from the HttpClient instance. The timeout only applies to the xxxAsync methods that cause a request/response to be initiated. If the timeout is reached, the for that request will be cancelled. +You can use to set a default timeout for all HTTP requests from the HttpClient instance. The timeout only applies to the xxxAsync methods that cause a request/response to be initiated. If the timeout is reached, the for that request is cancelled. -Some Additional timeouts can be set if you construct the HttpClient passing in a instance: +You can set some additional timeouts if you pass in a instance when constructing the HttpClient object: | **Property** | **Description**| | ------------ | -------------- | -| | Specifies a timeout that is used when a request requires a new TCP connection to be created. If the timout occurs the request is cancelled. | -| | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, it is immediately closed, otherwise at the end of the current request. | -| | If a connection in the connection pool is idle for this long the connection will be closed. | -| | If request has an "Expect: 100-continue" header, it will delay sending content until the timeout or a "100-continue" response has been received. | +| | Specifies a timeout that's used when a request requires a new TCP connection to be created. If the timeout occurs, the request is cancelled. | +| | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, the connection is immediately closed; otherwise, the connection is closed at the end of the current request. | +| | If a connection in the connection pool is idle for this long, the connection is closed. | +| | If request has an "Expect: 100-continue" header, it delays sending content until the timeout or until a "100-continue" response is received. | -HttpClient will only resolve DNS entries when the connections are created, it does not track any TTL durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, the can be used to limit the lifetime of the connection so that DNS will be required when replacing the connection. +HttpClient only resolves DNS entries when the connections are created. It does not track any time to live (TTL) durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, you can use the to limit the lifetime of the connection so that DNS lookup is required when replacing the connection. ## Examples [!code-csharp[System.Net.Http.HttpClient#1](~/samples/snippets/csharp/VS_Snippets_Misc/system.net.http.httpclient/cs/source.cs#1)] From aabe7939c5a3e6d3ea91a6402040968837911f69 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 20 May 2022 14:27:08 -0700 Subject: [PATCH 11/12] Fix grammar --- xml/System.Net.Http/HttpClient.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 89090971863..64e3f3accd2 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -103,7 +103,7 @@ Starting with .NET Core 2.1, the by referencing it's [NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) and passing it to [`HttpClient`'s constructor](xref:System.Net.Http.HttpClient.%23ctor(System.Net.Http.HttpMessageHandler)) manually. +If this change is undesirable, on Windows you can continue to use by referencing its [NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) and passing it to [HttpClient's constructor](xref:System.Net.Http.HttpClient.%23ctor(System.Net.Http.HttpMessageHandler)) manually. ### Configure behavior using run-time configuration options From 918b6fccb32cc83d747353dd2d00af99776fad7b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 20 May 2022 15:00:13 -0700 Subject: [PATCH 12/12] Minor touch-ups --- xml/System.Net.Http/HttpClient.xml | 45 +++++++++++++----------------- 1 file changed, 19 insertions(+), 26 deletions(-) diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 64e3f3accd2..89d5a289f53 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -32,12 +32,13 @@ class instance acts as a session to send HTTP requests. An instance is a collection of settings applied to all requests executed by that instance. In addition, every instance uses its own connection pool, isolating its requests from requests executed by other instances. +## Remarks - ### Instancing +The class instance acts as a session to send HTTP requests. An instance is a collection of settings applied to all requests executed by that instance. In addition, every instance uses its own connection pool, isolating its requests from requests executed by other instances. - is intended to be instantiated once and reused throughout the life of an application. HttpClient is designed to pool connections and reuse a connection across multiple requests. If you instantiate an HttpClient class for every request, the number of sockets available under heavy loads will be exhausted. This exhaustion will result in errors. Following is an example that uses HttpClient correctly. +### Instancing + + is intended to be instantiated once and reused throughout the life of an application. HttpClient is designed to pool connections and reuse a connection across multiple requests. If you instantiate an HttpClient class for every request, the number of sockets available under heavy loads will be exhausted. This exhaustion will result in errors. Following is an example that uses HttpClient correctly. ```csharp public class GoodController : ApiController @@ -105,11 +106,11 @@ Starting with .NET Core 2.1, the by referencing its [NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) and passing it to [HttpClient's constructor](xref:System.Net.Http.HttpClient.%23ctor(System.Net.Http.HttpMessageHandler)) manually. -### Configure behavior using run-time configuration options +### Configure behavior using runtime configuration options -Certain aspects of 's behavior are customizable through [Run-time configuration options](/dotnet/core/run-time-config/networking). However, the behavior of these switches differs through .NET versions. For example, in .NET Core 2.1 - 3.1, you can configure whether is used by default, but that option is no longer available starting in .NET 5.0. +Certain aspects of 's behavior are customizable through [Runtime configuration options](/dotnet/core/run-time-config/networking). However, the behavior of these switches differs through .NET versions. For example, in .NET Core 2.1 - 3.1, you can configure whether is used by default, but that option is no longer available starting in .NET 5.0. -### Connection Pooling +### Connection pooling HttpClient pools HTTP connections where possible and uses them for more than one request. This can have a significant performance benefit, especially for HTTPS requests, as the connection handshake is only done once. @@ -131,28 +132,20 @@ You can change the buffering behavior on a per-request basis using the and related classes in the namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If you use the default buffering, the client memory usage will get very large, potentially resulting in substantially reduced performance. -### Thread Safety +### Thread safety The following methods are thread safe: -- - -- - -- - -- - -- - -- - -- - -- - -- - +- +- +- +- +- +- +- +- +- + ### Proxies By default, HttpClient reads proxy configuration from environment variables or user/system settings, depending on the platform. You can change this behavior by passing a or to, in order of precedence: