Http​Base​Protocol​Filter Http​Base​Protocol​Filter Http​Base​Protocol​Filter Class

Definition

The base protocol filter for an HttpClient instance.

public : sealed class HttpBaseProtocolFilter : IClosable, IHttpBaseProtocolFilter, IHttpBaseProtocolFilter2, IHttpBaseProtocolFilter3, IHttpBaseProtocolFilter4, IHttpFilterpublic sealed class HttpBaseProtocolFilter : IDisposable, IHttpBaseProtocolFilter, IHttpBaseProtocolFilter2, IHttpBaseProtocolFilter3, IHttpBaseProtocolFilter4, IHttpFilterPublic NotInheritable Class HttpBaseProtocolFilter Implements IDisposable, IHttpBaseProtocolFilter, IHttpBaseProtocolFilter2, IHttpBaseProtocolFilter3, IHttpBaseProtocolFilter4, IHttpFilter
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The HttpBaseProtocolFilter class provides the base filter or handler that is used by an HttpClient instance. If no additional filters are added to the HttpClient instance, then the HttpBaseProtocolFilter object will be the only filter.

The HttpBaseProtocolFilter class provides a set of properties for toggling various low-level HTTP stack behaviors.

Additional filters based on the IHttpFilter interface can be added to the filter chain applied to an HttpClient instance that can further handle or process the results from the HttpBaseProtocolFilter object.

The HttpBaseProtocolFilter object throws exceptions when sending HTTP requests or receiving response and network failures occur (loss of connectivity in airplane mode, for example). Developers using HttpClient in apps may prefer to add a filter to catch these exceptions and convert them to HTTP response codes instead.

Constructors

HttpBaseProtocolFilter() HttpBaseProtocolFilter() HttpBaseProtocolFilter()

Initializes a new instance of the HttpBaseProtocolFilter class.

public : HttpBaseProtocolFilter()public HttpBaseProtocolFilter()Public Sub New()
Attributes

Properties

AllowAutoRedirect AllowAutoRedirect AllowAutoRedirect

Get or set a value that indicates whether the HttpBaseProtocolFilter should follow redirection responses.

public : PlatForm::Boolean AllowAutoRedirect { get; set; }public bool AllowAutoRedirect { get; set; }Public ReadWrite Property AllowAutoRedirect As bool
Value
PlatForm::Boolean bool bool

A value that indicates whether the HttpBaseProtocolFilter should follow redirection responses.

This value is true if the if HttpBaseProtocolFilter should follow redirection responses; otherwise false. The default value is true.

Attributes

Remarks

Set AllowAutoRedirect to true if you want the HttpBaseProtocolFilter to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set internally by the system.

If AllowAutoRedirect is set to false, all HTTP responses with an HTTP status code from 300 to 399 are returned to whatever called the HttpBaseProtocolFilter, which might another filter that might then return them to the app.

The Authorization header is cleared on auto-redirects and the HttpBaseProtocolFilter automatically tries to re-authenticate to the redirected location. In practice, this means that an app can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the app must implement a custom authentication module using a filter.

AllowUI AllowUI AllowUI

Get or set a value that indicates whether the HttpBaseProtocolFilter can prompt for user credentials when requested by the server.

public : PlatForm::Boolean AllowUI { get; set; }public bool AllowUI { get; set; }Public ReadWrite Property AllowUI As bool
Value
PlatForm::Boolean bool bool

A value that indicates whether HttpBaseProtocolFilter can prompt for user credentials when requested by the server.

This value is true if HttpBaseProtocolFilter can prompt for user credentials when requested; otherwise false. The default value is true.

Attributes

AutomaticDecompression AutomaticDecompression AutomaticDecompression

Gets or sets a value that indicates whether the HttpBaseProtocolFilter can automatically decompress the HTTP content response.

public : PlatForm::Boolean AutomaticDecompression { get; set; }public bool AutomaticDecompression { get; set; }Public ReadWrite Property AutomaticDecompression As bool
Value
PlatForm::Boolean bool bool

A value that indicates whether HttpBaseProtocolFilter can automatically decompress the HTTP content response.

This value is true if the if HttpBaseProtocolFilter can automatically decompress the HTTP content response; otherwise false. The default value is true.

Attributes

Remarks

When this property is set to true, the Accept-Encoding header is added to the headers and set to allow gzip and compress.

CacheControl CacheControl CacheControl

Get or set the read and write cache control behavior to be used on the HttpBaseProtocolFilter object.

public : HttpCacheControl CacheControl { get; }public HttpCacheControl CacheControl { get; }Public ReadOnly Property CacheControl As HttpCacheControl
Value
HttpCacheControl HttpCacheControl HttpCacheControl

The cache control behavior to be used on the HttpBaseProtocolFilter object.

Attributes

Remarks

The CacheControl property gets an HttpCacheControl object that allows access to the read and write cache control behavior used by the HttpBaseProtocolFilter object. HTTP read requests can use the local HTTP cache for the responses. Content returned by HTTP requests can be written to the local HTTP cache.

The CacheControl property allows a developer to set simple read and write cache control behavior on the HttpBaseProtocolFilter object. To use this feature, an app creates an HttpClient object with a new HttpBaseProtocolFilter object . The CacheControl property on the HttpBaseProtocolFilter returns an HttpCacheControl object. Properties on the HttpCacheControl object are used to set to the read and write cache control behavior for the HttpBaseProtocolFilter and the associated HttpClient object. This determines the read and write cache behavior on responses to HttpClient requests.

Developers can still use the HTTP Cache-Control header for more complete control over caching. The HttpCacheDirectiveHeaderValueCollection provides a collection container for instances of the cache directives in Cache-Control HTTP header on HTTP content associated with an HTTP request or response. The Cache-Control header lets an app control caching behavior used by a server on HTTP content.

See Also

ClientCertificate ClientCertificate ClientCertificate

Get or set the client SSL certificate that will be sent to the server if the server requests a client certificate.

public : Certificate ClientCertificate { get; set; }public Certificate ClientCertificate { get; set; }Public ReadWrite Property ClientCertificate As Certificate
Value
Certificate Certificate Certificate

The client SSl certificate.

Attributes

CookieManager CookieManager CookieManager

Get the HttpCookieManager with the cookies associated with an app.

public : HttpCookieManager CookieManager { get; }public HttpCookieManager CookieManager { get; }Public ReadOnly Property CookieManager As HttpCookieManager
Value
HttpCookieManager HttpCookieManager HttpCookieManager

The HttpCookieManager object that contains the cookies associated with an app.

Attributes

Remarks

The HttpCookieManager object allows a developer to add or delete an HttpCookie or view the cookies associated with an app.

CookieUsageBehavior CookieUsageBehavior CookieUsageBehavior

Gets or sets the cookie usage behavior. By default, cookies are handled automatically.

public : HttpCookieUsageBehavior CookieUsageBehavior { get; set; }public HttpCookieUsageBehavior CookieUsageBehavior { get; set; }Public ReadWrite Property CookieUsageBehavior As HttpCookieUsageBehavior
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

IgnorableServerCertificateErrors IgnorableServerCertificateErrors IgnorableServerCertificateErrors

Get a vector of SSL server certificate errors that the app might subsequently choose to ignore.

public : IVector<ChainValidationResult> IgnorableServerCertificateErrors { get; }public IList<ChainValidationResult> IgnorableServerCertificateErrors { get; }Public ReadOnly Property IgnorableServerCertificateErrors As IList<ChainValidationResult>
Value
IVector<ChainValidationResult> IList<ChainValidationResult> IList<ChainValidationResult>

A vector of SSL server certificate errors that the app might subsequently choose to ignore.

Attributes

Remarks

SSL server certificate errors should only be ignored in advanced scenarios. Disregarding server certificate errors classified as either Ignorable or Fatal may result in the loss of privacy or integrity of the content passed over the SSL session.

MaxConnectionsPerServer MaxConnectionsPerServer MaxConnectionsPerServer

Get or set the maximum number of TCP connections allowed per HTTP server by the HttpBaseProtocolFilter object.

public : unsigned short MaxConnectionsPerServer { get; set; }public uint MaxConnectionsPerServer { get; set; }Public ReadWrite Property MaxConnectionsPerServer As uint
Value
unsigned short uint uint

The maximum number of connections allowed per HTTP server.

Attributes

Remarks

The MaxConnectionsPerServer property determines the maximum number of TCP connections to an HTTP server allowed on the HttpBaseProtocolFilter object.

MaxVersion MaxVersion MaxVersion

Gets or sets the version of the HTTP protocol used.

public : HttpVersion MaxVersion { get; set; }public HttpVersion MaxVersion { get; set; }Public ReadWrite Property MaxVersion As HttpVersion
Value
HttpVersion HttpVersion HttpVersion

An enumeration value that specifies the version of HTTP used.

Attributes

Examples

The following code shows how to create an HttpClient that uses HTTP 1.1 rather than the default HTTP 2.0.

HttpBaseProtocolFilter filter = new HttpBaseProtocolFilter(); 

filter.MaxVersion = HttpVersion.Http11;

HttpClient client = new HttpClient(filter);

Remarks

By default, when a new request is started using Windows.Web.Http.HttpClient, it uses HTTP 2.0. To create an instance of HttpClient that uses HTTP 1.1 instead, set this property to HttpVersion.Http11 on a filter, and then create a new instance of HttpClient, passing the filter as an argument to the HttpClient constructor.

ProxyCredential ProxyCredential ProxyCredential

Get or set the credentials to be used to negotiate with an HTTP proxy.

public : PasswordCredential ProxyCredential { get; set; }public PasswordCredential ProxyCredential { get; set; }Public ReadWrite Property ProxyCredential As PasswordCredential
Value
PasswordCredential PasswordCredential PasswordCredential

The credentials to be used to negotiate with an HTTP proxy.

Attributes

Remarks

The system normally determines the proxy credentials to use automatically. This property only needs to be set in advanced scenarios.

ServerCredential ServerCredential ServerCredential

Get or set the credentials to be used to authenticate with an HTTP server.

public : PasswordCredential ServerCredential { get; set; }public PasswordCredential ServerCredential { get; set; }Public ReadWrite Property ServerCredential As PasswordCredential
Value
PasswordCredential PasswordCredential PasswordCredential

The credentials to be used to authenticate with an HTTP server.

Attributes

Remarks

The system normally determines the credentials needed to authenticate with an HTTP server automatically. This property only needs to be set in advanced scenarios.

UseProxy UseProxy UseProxy

Get or set a value that indicates whether the HttpBaseProtocolFilter can use a proxy for sending HTTP requests.

public : PlatForm::Boolean UseProxy { get; set; }public bool UseProxy { get; set; }Public ReadWrite Property UseProxy As bool
Value
PlatForm::Boolean bool bool

A value that indicates whether HttpBaseProtocolFilter can use a proxy to send HTTP requests.

This value is true if HttpBaseProtocolFilter can use a proxy to send requests; otherwise false. The default value is true to allow proxies to be used.

Attributes

Remarks

It is possible for this property to be true and a proxy exists, but HttpBaseProtocolFilter still doesn't use the proxy. This can occur depending on WPAD settings and whether the target URI is to an internal versus an external web server.

Many companies require the use of proxies to communicate with HTTP from a local intranet to the Internet.

Methods

ClearAuthenticationCache() ClearAuthenticationCache() ClearAuthenticationCache()

Clears authentication credentials currently cached on the device.

public : void ClearAuthenticationCache()public void ClearAuthenticationCache()Public Function ClearAuthenticationCache() As void
Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Close() Close() Close()

Closes the HttpBaseProtocolFilter instance and releases allocated resources.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net
Attributes

Remarks

The Close method releases allocated resources used by the HttpBaseProtocolFilter instance. The Close method can be used to manage the lifetime of system resources (the network socket used by the HttpBaseProtocolFilter, for example) that are used by a Windows Runtime object.

In the .NET Framework 4.5, this method is projected as the Dispose method. In Visual C++ component extensions (C++/CX), this method is projected as part of the destructor (delete operator).

Apps written in JavaScript, C#, or VB.NET use garbage collection to release resources. So the HttpBaseProtocolFilter object and associated resources doesn't get released until the garbage collection pass runs. The Close method allows an app to release these resources early rather than waiting for the object to be released by garbage collection.

Apps written in C++ or CX don't have a Close method since these apps can destroy the object deterministically. In C++ and CX, objects are released when they fall out of program scope or as part of the destructor (delete operator) for the object.

Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Dispose
Attributes

SendRequestAsync(HttpRequestMessage) SendRequestAsync(HttpRequestMessage) SendRequestAsync(HttpRequestMessage)

Send an HTTP request using the HttpBaseProtocolFilter as an asynchronous operation.

public : IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request)public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request)Public Function SendRequestAsync(request As HttpRequestMessage) As IAsyncOperationWithProgress( Of HttpResponseMessage, HttpProgress )
Parameters
request
HttpRequestMessage HttpRequestMessage HttpRequestMessage

The HTTP request message to send.

Returns
Attributes

Remarks

This operation will not block. The returned IAsyncOperationWithProgress(HttpResponseMessage, HttpProgress) object will complete once the entire HTTP response message is received.

Below are exceptions that this function throws.

E_INVALIDARG

The request parameter was a null reference (Nothing in Visual Basic).

E_ILLEGAL_METHOD_CALL

The request message was already sent by the HttpBaseProtocolFilter instance.

Events

ServerCustomValidationRequested ServerCustomValidationRequested ServerCustomValidationRequested

This event is raised when the SSL/TLS connection is being established with the server. You should implement an event handler for this event if you need to perform extra validation (in addition to the OS default) of the server SSL certificate.

public : event TypedEventHandler ServerCustomValidationRequestedpublic event TypedEventHandler ServerCustomValidationRequestedPublic Event ServerCustomValidationRequested
Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

Default OS validation of the server certificate is performed before raising this event. If the certificate fails this validation, the connection is terminated and your event handler is not called.

In order to skip parts of the OS validation (not recommended for production scenarios), use the IgnorableServerCertificateErrors property to specify the errors that you want to ignore. Then as long as the certificate does not have any other errors, the OS validation will be considered successful and your event handler will be called.

The event handler code is executed as part of a synchronous callback in the OS during the SSL/TLS connection establishment. Avoid performing long-running tasks within the event handler code to prevent the server from timing out during the connection.

If you need to call async APIs within your event handler code, you must take a deferral (See HttpServerCustomValidationArgs.GetDeferral ) before calling the asynchronous APIs. Once you are done, call the deferral.Complete method to return control from your handler code.

The following snippet shows how to subscribe to this event.


HttpBaseProtocolFilter.ServerCustomValidationRequest += (sender, args) =>
{
    var cert = args.ServerCertificate
    // Your custom cert validation code here.
}