WinHttpHandler Class

Definition

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
Inheritance
WinHttpHandler

Remarks

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.

Constructors

WinHttpHandler()

Initializes a new instance of the WinHttpHandler class.

Properties

AutomaticDecompression

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

AutomaticRedirection

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

CheckCertificateRevocationList

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

ClientCertificateOption

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 a collection of client authentication SSL certificates that are used for client authentication by the handler if the ClientCertificateOption property is set to Manual.

CookieContainer

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.

CookieUsePolicy

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.

DefaultProxyCredentials

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

EnableMultipleHttp2Connections

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.

MaxAutomaticRedirections

Gets or sets the maximum number of allowed HTTP redirects.

MaxConnectionsPerServer

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

MaxResponseDrainSize

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

MaxResponseHeadersLength

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

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 the custom proxy when the WindowsProxyUsePolicy property is set to use a custom proxy.

ReceiveDataTimeout

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

ReceiveHeadersTimeout

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

SendTimeout

Gets or sets the timeout for sending a request.

ServerCertificateValidationCallback

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

ServerCredentials

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

SslProtocols

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

TcpKeepAliveEnabled

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

TcpKeepAliveInterval

Gets or sets the TCP keep-alive interval.

TcpKeepAliveTime

Gets or sets the TCP keep-alive timeout.

WindowsProxyUsePolicy

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.

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 WinHttpHandler, 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)
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.

ToString()

Returns a string that represents the current object.

(Inherited from Object)

Applies to