Windows.Web.Http.Filters namespace

Applies to Windows and Windows Phone

Provides classes to send HTTP requests and an interface to create filters to target HTTP and REST services in Windows Store apps.

Members

The Windows.Web.Http.Filters namespace has these types of members:

Classes

The Windows.Web.Http.Filters namespace has these classes.

ClassDescription
HttpBaseProtocolFilter The base protocol filter for an HttpClient instance.
HttpCacheControl Provides control of the local HTTP cache for responses to HTTP requests by methods in the Windows.Web.Http and Windows.Web.Http.Filters namespaces.

 

Enumerations

The Windows.Web.Http.Filters namespace has these enumerations.

EnumerationDescription
HttpCacheReadBehavior Indicates if read requests by class methods in the Windows.Web.Http and Windows.Web.Http.Filters namespaces use the local HTTP cache for the response.
HttpCacheWriteBehavior Indicates if content returned by requests used by class methods in the Windows.Web.Http and Windows.Web.Http.Filters namespaces is written to the local HTTP cache.

 

Interfaces

The Windows.Web.Http.Filters namespace defines these interfaces.

InterfaceDescription
IHttpFilter An interface used to implement custom filters for an HttpClient instance.

 

Remarks

The Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces provides an HTTP programming interface for Windows Store apps that want to connect to HTTP services. The HTTP API provides consistent support in JavaScript, C#, VB.NET, and C++ for developers. The API also supports adding custom filters on requests and responses. Filters can simplify handling more complex network issues. The API also lets an app control read and write caching behavior.

Classes in the Windows.Web.Http namespace support the use of filters based on the classes in the Windows.Web.Http.Filters namespace. Classes in the Windows.Web.Http.Filters namespace also let an app control read and write caching behavior on the client. The HttpCacheDirectiveHeaderValueCollection in the Windows.Web.Http.Headers 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 have more control over caching behavior.

Classes in the Windows.Web.Http.Headers namespace represent HTTP headers as defined in RFC 2616 by the IETF.

The HttpClient class in the Windows.Web.Http namespace provides a base class for sending HTTP requests and receiving HTTP responses. Filters provide a handler mechanism to help with common HTTP service issues. Simple filters can be chained together in a sequence to handle more complex HTTP service issues.

An HTTP filter is a black box which takes an HTTP request message and produces an HTTP response message. How the filter gets an HTTP response is determined by the filter developer. Filters commonly add or change headers, handle authorization (possibly using the WebAuthenticationBroker), or allow or disallow a request based on network conditions. Filters usually make changes and then pass the request to an inner filter, which is typically set when a filter is constructed.

This approach allows a filter to be only responsible for a specific aspect of an HTTP request execution and delegate other aspects to other filters. A filter can implement caching, authentication, redirects, cookies, actual communication with the server, or a combination of these. The bottom-most (base) filter will usually be the one that does actual communication with the network.

Many apps that use HTTP for network access often need to respond to a variety of conditions. Some common examples include:

  • Network retry (with back-off).
  • Adapting to metered networks (when a network connection is roaming, for example).
  • Authentication to social network sites.
  • Logging and telemetry.

It’s not hard to handle any of these network issues by themselves. This becomes a complex problem when several of these issues are combined. Support for custom filters in the Windows.Web.Http.Filters namespace enables developers to create modular code for simple filters. A series of simple filters can be linked into a chain of filters to handle complex combinations of issues. The developer chooses everything about the filter chain:

  • The filters to add.
  • The order to place them in the filter chain.

HttpClient is the main class used to send and receive requests over HTTP. HttpBaseProtocolFilter is what HttpClient uses to send and receive data. So HttpBaseProtocolFilter is typically the bottom of any custom filter chain. HttpBaseProtocolFilter can also be used to control caching and other behavior of the HTTP connection. Each HttpClient instance can have a different filter chain or pipeline.

Drawing of an HTTP filter chain

To write a custom filter, an app implements a custom version of the IHttpFilter interface. The code to implement the filter behavior is in the IHttpFilter.SendRequestAsync method. Filters can be written in C#/VB.NET or C++. Filters can be called and used from any language supported for Windows Store apps including JavaScript.

The sample code shows a filter to add a custom header to HTTP requests and responses.


public class PlugInFilter : IHttpFilter {
    private IHttpFilter innerFilter;

    public PlugInFilter(IHttpFilter innerFilter) {
        if (innerFilter == null) {
            throw new ArgumentException("innerFilter cannot be null.");
        }
        this.innerFilter = innerFilter;
    }

    public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request) {
        return AsyncInfo.Run<HttpResponseMessage, HttpProgress>(async (cancellationToken, progress) =>
        {
            request.Headers.Add("Custom-Header", "CustomRequestValue");
            HttpResponseMessage response = await innerFilter.SendRequestAsync(request).AsTask(cancellationToken, progress);

            cancellationToken.ThrowIfCancellationRequested();

            response.Headers.Add("Custom-Header", "CustomResponseValue");
        return response;
        });
    }

    public void Dispose() {
        innerFilter.Dispose();
        GC.SuppressFinalize(this);
    }
}


To use a filter, an app uses the HttpClient(IHttpFilter) constructor passing the interface of the filter to use for the HttpClient instance. To set up the filter chain, the new filter is linked to a previous filter and to HttpBaseProtocolFilter at the bottom.

The sample code shows creating an HttpClient to use a custom filter.



internal static void CreateHttpClient(ref HttpClient httpClient)
{
    if (httpClient != null) {
        httpClient.Dispose();
    }

    // HttpClient can be extended by plugging multiple filters together,
    // providing HttpClient with the configured filter pipeline.
    var baseFilter = new HttpBaseProtocolFilter();

    // Adds a custom header to every request and response message.
    var myFilter = new PlugInFilter(baseFilter);
    httpClient = new HttpClient(myFilter);

}



Requirements

Minimum supported client

Windows 8.1

Minimum supported server

Windows Server 2012 R2

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Namespace

Windows.Web.Http.Filters
Windows::Web::Http::Filters [C++]

Metadata

Windows.winmd

See also

HttpClient
Windows.Web.Http
Windows.Web.Http.Headers

 

 

Show:
© 2014 Microsoft