HttpBaseProtocolFilter HttpBaseProtocolFilter HttpBaseProtocolFilter HttpBaseProtocolFilter Class

The base protocol filter for an HttpClient instance.

Syntax

Declaration

public sealed class HttpBaseProtocolFilterpublic sealed class HttpBaseProtocolFilterPublic NotInheritable Class HttpBaseProtocolFilterpublic sealed class HttpBaseProtocolFilter

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 summary

Initializes a new instance of the HttpBaseProtocolFilter class.

Properties summary

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

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

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

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

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

Get the HttpCookieManager with the cookies associated with an app.

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

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

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

Gets or sets the version of the HTTP protocol used.

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

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

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

Methods summary

Clears authentication credentials currently cached on the device.

Closes the HttpBaseProtocolFilter instance and releases allocated resources.

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

Events summary

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.

Constructors

  • HttpBaseProtocolFilter()
    HttpBaseProtocolFilter()
    HttpBaseProtocolFilter()
    HttpBaseProtocolFilter()

    Initializes a new instance of the HttpBaseProtocolFilter class.

    public HttpBaseProtocolFilter()public New()Public Sub New()public HttpBaseProtocolFilter()

Properties

  • AllowAutoRedirect
    AllowAutoRedirect
    AllowAutoRedirect
    AllowAutoRedirect

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

    public bool AllowAutoRedirect { get; set; }public bool AllowAutoRedirect { get; set; }Public ReadWrite Property AllowAutoRedirect As boolpublic bool AllowAutoRedirect { get; set; }

    Property Value

    • bool
      bool
      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.

    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
    AllowUI

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

    public bool AllowUI { get; set; }public bool AllowUI { get; set; }Public ReadWrite Property AllowUI As boolpublic bool AllowUI { get; set; }

    Property Value

    • bool
      bool
      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.

  • AutomaticDecompression
    AutomaticDecompression
    AutomaticDecompression
    AutomaticDecompression

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

    public bool AutomaticDecompression { get; set; }public bool AutomaticDecompression { get; set; }Public ReadWrite Property AutomaticDecompression As boolpublic bool AutomaticDecompression { get; set; }

    Property Value

    • bool
      bool
      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.

    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
    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 HttpCacheControlpublic HttpCacheControl CacheControl { get; }

    Property Value

    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.

  • ClientCertificate
    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 Certificatepublic Certificate ClientCertificate { get; set; }

    Property Value

  • CookieManager
    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 HttpCookieManagerpublic HttpCookieManager CookieManager { get; }

    Property Value

    Remarks

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

  • CookieUsageBehavior
    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 HttpCookieUsageBehaviorpublic HttpCookieUsageBehavior CookieUsageBehavior { get; set; }

    Property Value

  • IgnorableServerCertificateErrors
    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 IVector<ChainValidationResult> IgnorableServerCertificateErrors { get; }Public ReadOnly Property IgnorableServerCertificateErrors As IVector<ChainValidationResult>public IVector<ChainValidationResult> IgnorableServerCertificateErrors { get; }

    Property Value

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

    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
    MaxConnectionsPerServer

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

    public uint MaxConnectionsPerServer { get; set; }public uint MaxConnectionsPerServer { get; set; }Public ReadWrite Property MaxConnectionsPerServer As uintpublic uint MaxConnectionsPerServer { get; set; }

    Property Value

    • uint
      uint
      uint
      uint

      The maximum number of connections allowed per HTTP server.

    Remarks

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

  • MaxVersion
    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 HttpVersionpublic HttpVersion MaxVersion { get; set; }

    Property Value

    Remarks

    By default, when a new request is started using 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.

    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);
    
  • ProxyCredential
    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 PasswordCredentialpublic PasswordCredential ProxyCredential { get; set; }

    Property Value

    Remarks

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

  • ServerCredential
    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 PasswordCredentialpublic PasswordCredential ServerCredential { get; set; }

    Property Value

    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
    UseProxy

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

    public bool UseProxy { get; set; }public bool UseProxy { get; set; }Public ReadWrite Property UseProxy As boolpublic bool UseProxy { get; set; }

    Property Value

    • bool
      bool
      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.

    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()
    ClearAuthenticationCache()

    Clears authentication credentials currently cached on the device.

    public void ClearAuthenticationCache()public void ClearAuthenticationCache()Public Function ClearAuthenticationCache() As voidpublic void ClearAuthenticationCache()
  • Close()
    Close()
    Close()
    Close()

    Closes the HttpBaseProtocolFilter instance and releases allocated resources.

    public void Close()public void Close()Public Function Close() As voidpublic void Close()

    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.

  • SendRequestAsync(HttpRequestMessage)
    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 )public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request)

    Parameters

    Returns

    • The object representing the asynchronous operation.

    Remarks

    This operation will not block. The returned IAsyncOperationWithProgress<TResult, TProgress> object will complete once the entire HTTP response message is received.

Events

  • ServerCustomValidationRequested
    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 ServerCustomValidationRequestedpublic event TypedEventHandler ServerCustomValidationRequested

    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 GetDeferral() ) before calling the asynchronous APIs. Once you are done, call the 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.
    }
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.Web.Http.Filters.dll