HttpClientHandler Class

Definition

The default message handler used by HttpClient in .NET Framework and .NET Core 2.0 and earlier.

public ref class HttpClientHandler : System::Net::Http::HttpMessageHandler
public class HttpClientHandler : System.Net.Http.HttpMessageHandler
type HttpClientHandler = class
    inherit HttpMessageHandler
Public Class HttpClientHandler
Inherits HttpMessageHandler
Inheritance
HttpClientHandler
Derived

Examples

static async Task Main()
{
   // Create an HttpClientHandler object and set to use default credentials
   HttpClientHandler handler = new HttpClientHandler();
   handler.UseDefaultCredentials = true;

   // Create an HttpClient object
   HttpClient client = new HttpClient(handler);

   // Call asynchronous network methods in a try/catch block to handle exceptions
   try	
   {
      HttpResponseMessage response = await client.GetAsync("http://www.contoso.com/");

      response.EnsureSuccessStatusCode();

      string responseBody = await response.Content.ReadAsStringAsync();
      Console.WriteLine(responseBody);
   }  
   catch(HttpRequestException e)
   {
       Console.WriteLine("\nException Caught!");	
       Console.WriteLine("Message :{0} ",e.Message);
   }

   // Need to call dispose on the HttpClient and HttpClientHandler objects 
   // when done using them, so the app doesn't leak resources
   handler.Dispose(true);
   client.Dispose(true);
}

The preceding code example uses an async Task Main() entry point. That feature requires C# 7.1 or later.

Remarks

The HttpClientHandler class and classes derived from it enable developers to configure a variety of options ranging from proxies to authentication.

HttpClientHandler in .NET Core

Starting with .NET Core 2.1, the System.Net.Http.SocketsHttpHandler class instead of HttpClientHandler provides the implementation used by higher-level HTTP networking APIs. You can configure your application to use HttpClientHandler instead in any of the following ways:

  • By calling the AppContext.SetSwitch method as follows:

    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
    
    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False)
    
  • By defining the System.Net.Http.UseSocketsHttpHandler switch in the .netcore.runtimeconfig.json configuration file:

    "runtimeOptions": {
      "configProperties": {
          "System.Net.Http.UseSocketsHttpHandler": false
      }
    }
    
  • By defining an environment variable named DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER and setting it to either false or 0.

Constructors

HttpClientHandler()

Creates an instance of a HttpClientHandler class.

Properties

AllowAutoRedirect

Gets or sets a value that indicates whether the handler should follow redirection responses.

AutomaticDecompression

Gets or sets the type of decompression method used by the handler for automatic decompression of the HTTP content response.

CheckCertificateRevocationList

Gets or sets a value that indicates whether the certificate is checked against the certificate authority revocation list.

ClientCertificateOptions

Gets or sets a value that indicates if the certificate is automatically picked from the certificate store or if the caller is allowed to pass in a specific client certificate.

ClientCertificates

Gets the collection of security certificates that are associated requests to the server.

CookieContainer

Gets or sets the cookie container used to store server cookies by the handler.

Credentials

Gets or sets authentication information used by this handler.

DangerousAcceptAnyServerCertificateValidator

Gets a cached delegate that always returns true.

DefaultProxyCredentials

When the default (system) proxy is being used, gets or sets the credentials to submit to the default proxy server for authentication. The default proxy is used only when UseProxy is set to true and Proxy is set to null.

MaxAutomaticRedirections

Gets or sets the maximum number of redirects that the handler follows.

MaxConnectionsPerServer

Gets or sets the maximum number of concurrent connections (per server endpoint) allowed when making requests using an HttpClient object. Note that the limit is per server endpoint, so for example a value of 256 would permit 256 concurrent connections to http://www.adatum.com/ and another 256 to http://www.adventure-works.com/.

MaxRequestContentBufferSize

Gets or sets the maximum request content buffer size used by the handler.

MaxResponseHeadersLength

Gets or sets the maximum length, in kilobytes (1024 bytes), of the response headers. For example, if the value is 64, then 65536 bytes are allowed for the maximum response headers' length.

PreAuthenticate

Gets or sets a value that indicates whether the handler sends an Authorization header with the request.

Properties

Gets a writable dictionary (that is, a map) of custom properties for the HttpClient requests. The dictionary is initialized empty; you can insert and query key-value pairs for your custom handlers and special processing.

Proxy

Gets or sets proxy information used by the handler.

ServerCertificateCustomValidationCallback

Gets or sets a callback method to validate the server certificate.

SslProtocols

Gets or sets the TLS/SSL protocol used by the HttpClient objects managed by the HttpClientHandler object.

SupportsAutomaticDecompression

Gets a value that indicates whether the handler supports automatic response content decompression.

SupportsProxy

Gets a value that indicates whether the handler supports proxy settings.

SupportsRedirectConfiguration

Gets a value that indicates whether the handler supports configuration settings for the AllowAutoRedirect and MaxAutomaticRedirections properties.

UseCookies

Gets or sets a value that indicates whether the handler uses the CookieContainer property to store server cookies and uses these cookies when sending requests.

UseDefaultCredentials

Gets or sets a value that controls whether default credentials are sent with requests by the handler.

UseProxy

Gets or sets a value that indicates whether the handler uses a proxy for requests.

Methods

Dispose()

Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageHandler.

(Inherited from HttpMessageHandler)
Dispose(Boolean)

Releases the unmanaged resources used by the HttpClientHandler and optionally disposes of the managed resources.

Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetType()

Gets the Type of the current instance.

(Inherited from Object)
MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
SendAsync(HttpRequestMessage, CancellationToken)

Creates an instance of HttpResponseMessage based on the information provided in the HttpRequestMessage as an operation that will not block.

ToString()

Returns a string that represents the current object.

(Inherited from Object)

Applies to

See also