Meziantou.FrameworkHstsClientHandler Class
An HTTP message handler that automatically upgrades HTTP requests to HTTPS based on HSTS (HTTP Strict Transport Security) policies.
public sealed class HstsClientHandler : DelegatingHandlerRemarks
The handler follows redirects itself so that every hop is checked against the HSTS policies. Redirects the inner handler follows never reach this handler, so a redirect to an HSTS host would be requested over HTTP.
On the first request, when the inner handler is a SocketsHttpHandler or an HttpClientHandler configured to follow redirects, this handler turns its AllowAutoRedirect off and takes the redirects over, reusing its MaxAutomaticRedirections. That modifies the inner handler, so an instance shared with another HttpClient stops following redirects for that client too, and an instance that has already sent a request cannot be reconfigured at all and makes the first send throw. Pass maxAutomaticRedirections to the constructor to take the redirects over without touching the inner handler; that is also the only way to follow redirects when the inner handler is neither of those two types.
An inner handler already configured not to follow redirects, or of a type this handler does not recognize, keeps returning the redirect responses as is unless maxAutomaticRedirections is given.
Example
var policies = new HstsDomainPolicyCollection(includePreloadDomains: true);
using var client = new HttpClient(new HstsClientHandler(new SocketsHttpHandler(), policies), disposeHandler: true);
// Automatically upgrade to HTTPS as github.com is in the HSTS preload list
using var response = await client.GetAsync("http://github.com");- Inheritance
DelegatingHandlerHstsClientHandler
Constructors
| Name | Description |
|---|---|
| HstsClientHandler() | Initializes a new instance of the HstsClientHandler class with the default HSTS policy collection and no inner handler. |
| HstsClientHandler(HstsDomainPolicyCollection) | Initializes a new instance of the HstsClientHandler class with a custom HSTS policy collection and no inner handler. |
| HstsClientHandler(HttpMessageHandler) | Initializes a new instance of the HstsClientHandler class with the default HSTS policy collection. |
| HstsClientHandler(HttpMessageHandler?, HstsDomainPolicyCollection) | Initializes a new instance of the HstsClientHandler class with a custom HSTS policy collection. |
| HstsClientHandler(HttpMessageHandler?, HstsDomainPolicyCollection, int) | Initializes a new instance of the HstsClientHandler class that follows redirects itself without reconfiguring the inner handler. |
HstsClientHandler overloads
HstsClientHandler()
HstsClientHandler.csInitializes a new instance of the HstsClientHandler class with the default HSTS policy collection and no inner handler.
public HstsClientHandler()Remarks
The inner handler is left unset so the instance can be registered with IHttpClientFactory.AddHttpMessageHandler, which supplies it.
HstsClientHandler(HstsDomainPolicyCollection)
HstsClientHandler.csInitializes a new instance of the HstsClientHandler class with a custom HSTS policy collection and no inner handler.
public HstsClientHandler(HstsDomainPolicyCollection configuration)Parameters
configurationHstsDomainPolicyCollection- The HSTS policy collection to use for determining which requests to upgrade.
Remarks
The inner handler is left unset so the instance can be registered with IHttpClientFactory.AddHttpMessageHandler, which supplies it.
HstsClientHandler(HttpMessageHandler)
HstsClientHandler.csInitializes a new instance of the HstsClientHandler class with the default HSTS policy collection.
public HstsClientHandler(HttpMessageHandler innerHandler)Parameters
innerHandlerHttpMessageHandler- The inner HTTP message handler to delegate requests to.
HstsClientHandler(HttpMessageHandler?, HstsDomainPolicyCollection)
HstsClientHandler.csInitializes a new instance of the HstsClientHandler class with a custom HSTS policy collection.
public HstsClientHandler(HttpMessageHandler? innerHandler, HstsDomainPolicyCollection configuration)Parameters
innerHandlerHttpMessageHandler?- The inner HTTP message handler to delegate requests to, or
nullto let a handler factory supply it. configurationHstsDomainPolicyCollection- The HSTS policy collection to use for determining which requests to upgrade.
HstsClientHandler(HttpMessageHandler?, HstsDomainPolicyCollection, int)
HstsClientHandler.csInitializes a new instance of the HstsClientHandler class that follows redirects itself without reconfiguring the inner handler.
public HstsClientHandler(HttpMessageHandler? innerHandler, HstsDomainPolicyCollection configuration, int maxAutomaticRedirections)Parameters
innerHandlerHttpMessageHandler?- The inner HTTP message handler to delegate requests to, or
nullto let a handler factory supply it. configurationHstsDomainPolicyCollection- The HSTS policy collection to use for determining which requests to upgrade.
maxAutomaticRedirectionsint- The number of redirects to follow, or
0not to follow any. The inner handler must be configured not to follow redirects, or every hop it follows bypasses the HSTS upgrade.
Exceptions
ArgumentOutOfRangeExceptionmaxAutomaticRedirectionsis negative.