diff --git a/docs/fundamentals/networking/http/httpclient-guidelines.md b/docs/fundamentals/networking/http/httpclient-guidelines.md index bb610ac8cad6f..fcc4ab4df1578 100644 --- a/docs/fundamentals/networking/http/httpclient-guidelines.md +++ b/docs/fundamentals/networking/http/httpclient-guidelines.md @@ -12,7 +12,7 @@ The class sends HTTP ## DNS behavior - only resolves DNS entries when a connection is created. It does not track any time to live (TTL) durations specified by the DNS server. If DNS entries change regularly, which can happen in some scenarios, the client won't respect those updates. To solve this issue, you can limit the lifetime of the connection by setting the property, so that DNS lookup is repeated when the connection is replaced. Consider the following example: + only resolves DNS entries when a connection is created. It doesn't track anytime to live (TTL) durations specified by the DNS server. If DNS entries change regularly, which can happen in some scenarios, the client doesn't respect those updates. To solve this issue, you can limit the lifetime of the connection by setting the property, so that DNS lookup is repeated when the connection is replaced. Consider the following example: ```csharp var handler = new SocketsHttpHandler @@ -22,13 +22,13 @@ var handler = new SocketsHttpHandler var sharedClient = new HttpClient(handler); ``` -The preceding `HttpClient` is configured to reuse connections for 15 minutes. After the timespan specified by has elapsed and the connection has completed its last associated request (if any), this connection is closed. If there are any requests waiting in the queue, a new connection is created as needed. +The preceding `HttpClient` is configured to reuse connections for 15 minutes. After the timespan specified by elapses and the connection completes its last associated request (if any), this connection is closed. If there are any requests waiting in the queue, a new connection is created. The 15-minute interval was chosen arbitrarily for illustration purposes. You should choose the value based on the expected frequency of DNS or other network changes. ## Pooled connections -The connection pool for an is linked to the underlying . When the instance is disposed, it disposes all existing connections inside the pool. If you later send a request to the same server, a new connection must be recreated. As a result, there's a performance penalty for unnecessary connection creation. Moreover, TCP ports are not released immediately after connection closure. (For more information on that, see TCP `TIME-WAIT` in [RFC 9293](https://www.rfc-editor.org/rfc/rfc9293.html#section-3.3.2).) If the rate of requests is high, the operating system limit of available ports might be exhausted. To avoid port exhaustion problems, we [recommend](#recommended-use) reusing instances for as many HTTP requests as possible. +The connection pool for an is linked to the underlying . When the instance is disposed, it disposes all existing connections inside the pool. If you later send a request to the same server, a new connection must be recreated. As a result, there's a performance penalty for unnecessary connection creation. Moreover, TCP ports aren't released immediately after connection closure. (For more information on that, see TCP `TIME-WAIT` in [RFC 9293](https://www.rfc-editor.org/rfc/rfc9293.html#section-3.3.2).) If the rate of requests is high, the operating system limit of available ports might be exhausted. To avoid port exhaustion problems, we [recommend](#recommended-use) reusing instances for as many HTTP requests as possible. ## Recommended use @@ -41,16 +41,16 @@ To summarize recommended `HttpClient` use in terms of lifetime management, you s > [!TIP] > If you only use a limited number of instances, that's also an acceptable strategy. What matters is that they're not created and disposed with each request, as they each contain a connection pool. Using more than one instance is necessary for scenarios with multiple proxies or to separate cookie containers without completely disabling cookie handling. - - Using , you can have multiple, differently configured clients for different use cases. However, be aware that the factory-created clients are intended to be short-lived, and once the client is created, the factory no longer has control over it. + - Using , you can have multiple, differently configured clients for different use cases. However, the factory-created clients are intended to be short-lived, and once the client is created, the factory no longer has control over it. - The factory pools instances, and, if its lifetime hasn't expired, a handler can be reused from the pool when the factory creates a new instance. This reuse avoids any socket exhaustion issues. + The factory pools instances, and, if its lifetime isn't expired, a handler can be reused from the pool when the factory creates a new instance. This reuse avoids any socket exhaustion issues. If you desire the configurability that provides, we recommend using the [typed-client approach](../../../core/extensions/httpclient-factory.md#typed-clients). - In .NET Framework, use to manage your `HttpClient` instances. If you don't use the factory and instead create a new client instance for each request yourself, you can exhaust available ports. > [!WARNING] - > If your app requires cookies, it's recommended to avoid using . Pooling the instances results in sharing of objects. Unanticipated sharing might leak cookies between unrelated parts of the application. Moreover, when expires, the handler is recycled, meaning that all cookies stored in its are lost. + > If your app requires cookies, it's best to avoid using . Pooling the instances results in sharing of objects. Unanticipated sharing might leak cookies between unrelated parts of the application. Moreover, when expires, the handler is recycled, meaning that all cookies stored in its are lost. For more information about managing `HttpClient` lifetime with `IHttpClientFactory`, see [`IHttpClientFactory` guidelines](../../../core/extensions/httpclient-factory.md#httpclient-lifetime-management). @@ -64,7 +64,7 @@ The preceding code: - Relies on [Microsoft.Extensions.Http.Resilience](https://www.nuget.org/packages/Microsoft.Extensions.Http.Resilience) NuGet package. - Specifies a transient HTTP error handler, configured with retry pipeline that with each attempt will exponentially backoff delay intervals. -- Defines a pooled connection lifetime of fifteen minutes for the `socketHandler`. +- Defines a pooled connection lifetime of 15 minutes for the `socketHandler`. - Passes the `socketHandler` to the `resilienceHandler` with the retry logic. - Instantiates a shared `HttpClient` given the `resilienceHandler`.