The HttpClient class in C# serves as a session for making HTTP requests. An instance of HttpClient holds a collection of settings applied to all requests originating from it. Importantly, each HttpClient instance manages its own connection pool, isolating its requests from those made by other HttpClient instances.

Instantiation Best Practices

Its highly recommended too instantiate HttpClient once and reuse that single instance throughout the application's lifecycle. In modern .NET (.NET Core and later), HttpClient leverages connection pooling via its handler, reusing underlying connections across multiple requests. Creating a new HttpClient for every request, especially under heavy load, can exhaust the available socket resources, leading to SocketException errors.

Advanced configuration, such as setting specific options like connection timeouts or custom headers, can be achieved by providing a HttpMessageHandler (like HttpClientHandler or SocketsHttpHandler) to the HttpClient constructor. Once a request is made, the connection properties on the handler are immutable. If different requests require distinct configurations, it may be necessary to maintain multiple HttpClient instances, each tailored with the appropriate settings.

DNS Resolution and Connection Lifetimes

HttpClient resolves DNS entries only when a new connection is established. It does not actively monitor the Time-To-Live (TTL) specified by DNS servers. If DNS records change frequently, which can occur in dynamic environments like containerized applications, the client will not automatically recognize these updates. To mitigate this, you can control the connection's lifespan by configuring the SocketsHttpHandler.PooledConnectionLifetime property. Setting this property ensures that connections are periodically refreshed, forcing a new DNS lookup when a replacement connection is created.

// Example demonstrating pooled connection lifetime configuration
public class MyApiClient
{
    private static readonly HttpClient apiClient;

    static MyApiClient()
    {
        var socketsHandler = new SocketsHttpHandler
        {
            // Connections will be pooled and reused for up to 2 minutes
            PooledConnectionLifetime = TimeSpan.FromMinutes(2)
        };

        apiClient = new HttpClient(socketsHandler);
        apiClient.BaseAddress = new Uri("https://api.example.com");
    }

    // Methods to make API calls using apiClient...
}

For more sophisticated management of HttpClient instances, especially in complex applications, consider using IHttpClientFactory. This factory pattern provides a robust way to configure and manage the lifecycle of HttpClient objects.

Extending HttpClient

HttpClient can also serve as a base class for more specialized HTTP clients. For instance, you might create a CustomApiClient that includes methods tailored to a specific API. When deriving from HttpClient, it's generally advised not to override virtual methods. Instead, leverage the constructor overloads that accept a HttpMessageHandler to inject custom request processing logic (e.g., adding authentication headers before a request is sent).

Connection Pooling and Port Exhaustion

The connection pool managed by HttpClient is tied to the underlying SocketsHttpHandler. Disposing of an HttpClient instance also disposes of its active connections. If subsequent requests are made to the same server after disposal, new connections must be established, incurring performance overhead. Furthermore, closed TCP connections may remain in a TIME_WAIT state for a period, depending on OS settings. In high-throughput scenarios, this can lead to the exhaustion of available ephemeral ports on the operating system. To prevent port exhaustion, reusing HttpClient instances across as many HTTP requests as possible is the recommended approach.

Making HTTP Requests

Initializing HttpClient

// Adhering to recommended lifecycle management practices:
// https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use
private static readonly HttpClient sharedApiClient = new()
{
    BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
};

The above snippet initializes a single HttpClient instance as a static member, intended for reuse throughout the application's lifetime. The BaseAddress property is set to simplify subsequent requests by providing a common base URL.

Executing HTTP Requests

HttpClient provides a variety of asynchronous methods for issuing HTTP requests:

HTTP Method	Corresponding API Method
GET	GetAsync
GET (as byte array)	GetByteArrayAsync
GET (as stream)	GetStreamAsync
GET (as string)	GetStringAsync
POST	PostAsync
PUT	PutAsync