Edit

Guidelines for using HttpClient

  • Article

The System.Net.Http.HttpClient class sends HTTP requests and receives HTTP responses from a resource identified by a URI. An HttpClient instance is a collection of settings that's applied to all requests executed by that instance, and each instance uses its own connection pool, which isolates its requests from others. Starting in .NET Core 2.1, the SocketsHttpHandler class provides the implementation, making behavior consistent across all platforms.

DNS behavior

HttpClient 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 PooledConnectionLifetime property, so that DNS lookup is repeated when the connection is replaced. Consider the following example:

var handler = new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(15) // Recreate every 15 minutes
};
var sharedClient = new HttpClient(handler);

The preceding HttpClient is configured to reuse connections for 15 minutes. After the timespan specified by PooledConnectionLifetime has elapsed, the connection is closed and a new one is created.

Pooled connections

The connection pool for an HttpClient is linked to the underlying SocketsHttpHandler. When the HttpClient 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, see TCP TIME-WAIT in RFC 9293. So if the rate of requests is high, the operating system limit of available ports might be exhausted. To avoid port exhaustion problems, reusing HttpClient instance for as many HTTP requests as possible is recommended. This can be achieved by following the recommended usage.

  • In .NET Core and .NET 5+:

    • Use a static or singleton HttpClient instance with PooledConnectionLifetime set to the desired interval, such as two minutes, depending on expected DNS changes. This solves both the port exhaustion and DNS changes problems without adding the overhead of IHttpClientFactory. If you need to be able to mock your handler, you can register it separately.

    Tip

    Any reasonably limited number of HttpClient instances will work as well. What matters here is that they are 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 IHttpClientFactory, 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.

      The factory pools HttpMessageHandler instances, and, if its lifetime hasn't expired, a handler can be reused from the pool when the factory creates a new HttpClient instance. This reuse avoids any socket exhaustion issues.

      If you desire the configurability that IHttpClientFactory provides, we recommend using the typed-client approach.

  • In .NET Framework, use IHttpClientFactory to manage your HttpClient instances. If you create a new client instance for each request, you can exhaust available sockets.

    Tip

    If your app requires cookies, consider disabling automatic cookie handling or avoiding IHttpClientFactory. Pooling the HttpMessageHandler instances results in sharing of CookieContainer objects. Unanticipated CookieContainer object sharing often results in incorrect code.

HttpClient lifetime management

To summarize recommended HttpClient use in terms of lifetime management, you should use either long-lived clients with PooledConnectionLifetime set up (.NET Core and .NET 5+) or short-lived clients created by IHttpClientFactory.

To learn more about managing HttpClient lifetime with IHttpClientFactory, see IHttpClientFactory guidelines.

See also