HttpClientHandler Class

Summary

Provides the main implementation of the HttpMessageHandler that uses HttpClient to send HTTP requests and receive HTTP responses.

public class HttpClientHandler : HttpMessageHandler

Remarks

The HttpClientHandler class is the default handler for HttpClient. It handles the low-level details of sending HTTP requests over the network, including connection management, cookie handling, and authentication.

You can configure various aspects of the HTTP request behavior by setting properties on an instance of HttpClientHandler before it's assigned to an HttpClient.

Constructors

public HttpClientHandler()

Summary: Initializes a new instance of the HttpClientHandler class.

Properties

AllowAutoRedirect

public bool AllowAutoRedirect { get; set; }

Summary: Gets or sets a value that indicates whether the handler automatically follows redirection responses.

AutomaticDecompression

public DecompressionMethods AutomaticDecompression { get; set; }

Summary: Gets or sets a value that indicates the decompression methods that the handler supports.

ClientCertificateOptions

public ClientCertificateOption ClientCertificateOptions { get; set; }

Summary: Gets or sets a value that indicates the client certificate options.

CookieContainer

public CookieContainer CookieContainer { get; set; }

Summary: Gets or sets the collection of cookies to send with requests.

Credentials

public ICredentials Credentials { get; set; }

Summary: Gets or sets the credentials to be sent with requests.

MaxAutomaticRedirections

public int MaxAutomaticRedirections { get; set; }

Summary: Gets or sets the maximum number of automatic redirections.

MaxRequestContentBufferSize

public long MaxRequestContentBufferSize { get; set; }

Summary: Gets or sets the maximum number of bytes that will be buffered for the request content.

PreAuthenticate

public bool PreAuthenticate { get; set; }

Summary: Gets or sets a value that indicates whether the handler sends authentication information preemptively.

Proxy

public IWebProxy Proxy { get; set; }

Summary: Gets or sets the proxy used to send requests.

UseCookies

public bool UseCookies { get; set; }

Summary: Gets or sets a value that indicates whether the handler uses cookies.

UseProxy

public bool UseProxy { get; set; }

Summary: Gets or sets a value that indicates whether the handler uses a proxy.

Methods

Dispose

protected override void Dispose(bool disposing)

Parameters:

disposing: true to release both managed and unmanaged resources; false to release only unmanaged resources.

Summary: Releases the unmanaged resources used by the HttpClientHandler and optionally releases the managed resources.

Send

protected override Task<HttpResponseMessage> Send(HttpRequestMessage request, CancellationToken cancellationToken)

Parameters:

request: The HTTP request to send.

cancellationToken: A token that may be used to cancel the operation.

Summary: Sends an HTTP request to the specified server.

Example

Using HttpClientHandler to set custom behavior

                    
using System;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

public class Example
{
    public static async Task Main(string[] args)
    {
        // Create a HttpClientHandler with custom settings
        var handler = new HttpClientHandler
        {
            CookieContainer = new CookieContainer(),
            UseCookies = true,
            AllowAutoRedirect = true,
            MaxAutomaticRedirections = 5,
            Credentials = new NetworkCredential("user", "password"),
            PreAuthenticate = true,
            Proxy = new WebProxy("http://myproxy.example.com:8888")
        };

        // Create an HttpClient using the custom handler
        using (var httpClient = new HttpClient(handler))
        {
            try
            {
                HttpResponseMessage response = await httpClient.GetAsync("https://www.example.com");
                response.EnsureSuccessStatusCode(); // Throw if status code is not 2xx

                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException e)
            {
                Console.WriteLine($"Request error: {e.Message}");
            }
        }
    }
}
                    
                

Exceptions

When overridden in a derived class, this method may throw exceptions.

ArgumentNullException: The request parameter is null.
InvalidOperationException: The handler has already been disposed.
ObjectDisposedException: The HttpClientHandler has been disposed.