In two previous blogs I describe how to use HttpClient as well as how to use the HttpMessageHandler pipeline. What we haven’t done explicitly is showing when and how to use HttpClient, HttpClientHandler, and WebRequestHandler. This is the purpose of this blog.
The first thing to remember is that HttpClient uses the HttpMessageHandler pipeline for sending and receiving requests. The default handler implementations (HttpClientHandler and WebRequestHandler) both sit on top of HttpWebRequest which has a lot of properties for controlling how to deal with requests and responses. However, in order to stay simple, HttpClient doesn’t expose all these properties up front – it would make it unwieldy and show a lot of things that are rarely used.
If you need to access these properties then there are two ways of doing it: use either HttpClientHandler or WebRequestHandler. Both are HttpMessageHandlers hooked in as part of the HttpMessageHandler pipeline. Below we will describe when and how to use these handlers, how they differ, as well as how to combine them with your own handlers.
The default HttpClient is the simplest way in which you can start sending requests. A single HttpClient can be used to send as many HTTP requests as you want concurrently so in many scenarios you can just create one HttpClient and then use that for all your requests.
HttpClient has a few properties that are commonly used and which you can set up until the point where you start sending requests, namely:
|BaseAddress||Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.|
|DefaultRequestHeaders||Gets the headers which should be sent with each request.|
|MaxResponseContentBufferSize||Gets or sets the maximum number of bytes to buffer when reading the response content.|
|Timeout||Gets or sets the number of milliseconds to wait before the request times out.|
Here’s an example of how to create a simple HttpClient and issue a request while setting the timeout for all requests:
If you have additional handlers which you want to wire up as well then the simplest way is to use the HttpClientFactory class. Here’s an example wiring up 3 custom message handlers:
HttpClientHandler is an HttpMessageHandler with a common set of properties that works across most versions of the HttpWebRequest API. This is the default handler and so is what you get if you use the default constructor. However, in order to actually get access to the various properties (see below) you have to explicitly create it and then pass it to HttpClient.
|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.|
|ClientCertificateOptions||Gets or sets the collection of security certificates that are associated with this handler.|
|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.|
|MaxAutomaticRedirections||Gets or sets the maximum number of redirects that the handler follows.|
|MaxRequestContentBufferSize||Gets or sets the maximum request content buffer size used by the handler.|
|PreAuthenticate||Gets or sets a value that indicates whether the handler sends an Authorization header with the request.|
|Proxy||Gets or sets proxy information used by the handler.|
|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.|
Here’s an example of how to create an HttpClientHandler, set a property, and pass it to HttpClient:
Like above, you can combine your HttpClientHandler instance with other custom handlers, here’s what it looks like:
WebRequestHandler derives from HttpClientHandler but adds properties that generally only are available on full .NET. The WebRequestHandler is not included in the System.Net.Http DLL but rather in System.Net.Http.WebRequest DLL so you have to explicitly include that as a reference in order to see it. Otherwise it won’t show up.
|AllowPipelining||Gets or sets a value that indicates whether to pipeline the request to the Internet resource.|
|AuthenticationLevel||Gets or sets a value indicating the level of authentication and impersonation used for this request.|
|CachePolicy||Gets or sets the cache policy for this request.|
|ClientCertificates||Gets or sets the collection of security certificates that are associated with this request.|
|ContinueTimeout||Gets or sets the amount of time, in milliseconds, the application will wait for 100-continue from the server before uploading data.|
|ImpersonationLevel||Gets or sets the impersonation level for the current request.|
|MaxResponseHeadersLength||Gets or sets the maximum allowed length of the response headers.|
|ReadWriteTimeout||Gets or sets a time-out in milliseconds when writing a request to or reading a response from a server.|
|ServerCertificateValidationCallback||Gets or sets a callback for verifying the remote Secure Sockets Layer (SSL) certificate used for authentication.|
|UnsafeAuthenticatedConnectionSharing||Gets or sets a value that indicates whether to allow high-speed NTLM-authenticated connection sharing.|
Here’s an example of how to create an WebRequestHandler, set a property, and pass it to HttpClient:
Again, you can combine the WebRequestHandler with your own handlers as well – here’s what it looks like: