Windows.Web.Http.Filters Namespace
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Provides classes to send HTTP requests and an interface to create filters to target HTTP and REST services in UWP app.
Classes
| 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. |
| HttpServerCustomValidationRequestedEventArgs |
Provides data for the ServerCustomValidationRequested event. |
Interfaces
| IHttpFilter |
An interface used to implement custom filters for an HttpClient instance. |
Enums
| 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. |
| HttpCookieUsageBehavior |
Defines the cookie usage behavior that is used in the CookieUsageBehavior property. |
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 UWP app 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.
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 UWP app 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);
}