Share via

WinHttpHandler Class


Handles messages based on the WinHTTP interface of Windows. This class is intended for use in server environments.

public ref class WinHttpHandler : System::Net::Http::HttpMessageHandler
public class WinHttpHandler : System.Net.Http.HttpMessageHandler
type WinHttpHandler = class
    inherit HttpMessageHandler
Public Class WinHttpHandler
Inherits HttpMessageHandler


WinHttpHandler is similar to other existing classes such as HttpClientHandler. WinHttpHandler provides a handler underneath an HttpClient instance and is used to send HTTP requests out to a server and receive server responses. The WinHttpHandler implementation supports HTTP versions up to HTTP/2.

WinHttpHandler is designed to be used primarily in server environments by ASP.NET Core and other .NET applications that communicate with HTTP servers. WinHttpHandler also provides developers with more granular control over the application's HTTP communication than the HttpClientHandler class. This allows developers to implement more advanced HTTP scenarios or modify system defaults (for example, proxy settings, timeouts, and server SSL certificate validation).

WinHttpHandler is not intended to be a replacement for HttpClientHandler. Instead, it's a more advanced version that's provided for scenarios where HttpClientHandler is insufficient. WinHttpHandler is implemented as a thin wrapper on the WinHTTP interface of Windows and is only supported on Windows systems.

When using a chain of multiple handlers, WinHttpHandler should be at the bottom of the chain.

This class is also available for use in Desktop apps by installing it as a NuGet package. For more information, see System.Net.Http.WinHttpHandler NuGet package.

Starting in .NET 5, WinHttpHandler is no longer included in the System.Net.Http.dll assembly as part of the .NET runtime. For more information, see WinHttpHandler removed from .NET runtime.



Initializes a new instance of the WinHttpHandler class.



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


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


Gets or sets a value that indicates whether to check the revocation list of certificates during SSL certificate validation.


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.


Gets a collection of client authentication SSL certificates that are used for client authentication by the handler if the ClientCertificateOption property is set to Manual.


Gets or sets the managed cookie container object. This property is only used when the CookieUsePolicy property is set to UseSpecifiedCookieContainer. Otherwise, the SendAsync(HttpRequestMessage, CancellationToken) method will throw an exception.


Gets or sets a value that indicates how cookies should be managed and used. Developers can choose to ignore cookies, allow the handler to automatically manage them or manually handle them using a CookieContainer object.


Gets or sets the credentials used to authenticate the user to an authenticating proxy.


Gets or sets a value that indicates whether additional HTTP/2 connections can be established to the same server when the maximum number of concurrent streams is reached on all existing connections.


Gets or sets the maximum number of allowed HTTP redirects.


Gets or sets the maximum number of TCP connections allowed to a single server.


Gets or sets the maximum amount of data that can be drained from responses in bytes.


Gets or sets the maximum size of the header portion from the server response in bytes.


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


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.


Gets or sets the custom proxy when the WindowsProxyUsePolicy property is set to use a custom proxy.


Gets or sets the timeout for receiving the data portion of a response from the server.


Gets or sets the timeout for receiving the headers of a response from the server.


Gets or sets the timeout for sending a request.


Gets or sets a callback method to validate the server certificate. This callback is part of the SSL handshake.


Gets or sets the credentials to be used by the client to authenticate to the server.


Gets or sets the collection of TLS/SSL protocols supported by the client.


Gets or sets a value indicating whether TCP keep-alive is enabled.


Gets or sets the TCP keep-alive interval.


Gets or sets the TCP keep-alive timeout.


Gets or sets the proxy setting. This property can be set to disable the proxy, use a custom proxy, or use the proxy settings of WinHTTP or WinInet on the machine.



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

(Inherited from HttpMessageHandler)

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


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

(Inherited from Object)

Serves as the default hash function.

(Inherited from Object)

Gets the Type of the current instance.

(Inherited from Object)

Creates a shallow copy of the current Object.

(Inherited from Object)
Send(HttpRequestMessage, CancellationToken)

When overridden in a derived class, sends an HTTP request with the specified request and cancellation token. Otherwise, throws a NotSupportedException.

(Inherited from HttpMessageHandler)
SendAsync(HttpRequestMessage, CancellationToken)

Sends an HTTP request as an asynchronous operation.


Returns a string that represents the current object.

(Inherited from Object)

Applies to