diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index d98c99ca21a..3d5b005f33b 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -70,7 +70,11 @@ 10. - 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. + 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. + + However, long running applications using as a singleton may run into problems with not picking up DNS changes. A better approach for such cases is to utilize the `HttpClientFactory` introduced in .NET Core 2.1, which handles the lifetime of the underlying . It will also allow an application to use DI and inject a . + + Below is an example using HttpClient for a short-lived application that does not have DNS change concerns. For examples on how to use `HttpClientFactory` and DI, [refer to this guide on HttpClientFactory](https://docs.microsoft.com/en-us/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#multiple-ways-to-use-ihttpclientfactory). ```csharp public class GoodController : ApiController @@ -157,7 +161,12 @@ Certain aspects of 's behavior are customizable 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. + 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. + + However, long running applications using as a singleton may run into problems with not picking up DNS changes. A better approach for such cases is to utilize the `HttpClientFactory` introduced in .NET Core 2.1, which handles the lifetime of the underlying . It will also allow an application to use DI and inject a . + + Below is an example using HttpClient for a short-lived application that does not have DNS change concerns. For examples on how to use `HttpClientFactory` and DI, [refer to this guide on HttpClientFactory](https://docs.microsoft.com/en-us/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#multiple-ways-to-use-ihttpclientfactory). + ```csharp public class GoodController : ApiController