Windows.Web.Http.Filters 命名空间

参考

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

编辑

提供用于发送 HTTP 请求的类，以及用于在 UWP 应用中创建筛选器以面向 HTTP 和 REST 服务的接口。

类

HttpBaseProtocolFilter	HttpClient 实例的基本协议筛选器。
HttpCacheControl	通过 Windows.Web.Http 和 Windows.Web.Http.Filters 命名空间中的方法控制对 HTTP 请求的响应的本地 HTTP 缓存。
HttpServerCustomValidationRequestedEventArgs	为 ServerCustomValidationRequested 事件提供数据。

接口

IHttpFilter

用于为 HttpClient 实例实现自定义筛选器的接口。

枚举

HttpCacheReadBehavior	指示 Windows.Web.Http 和 Windows.Web.Http.Filters 命名空间中按类方法读取请求是否使用响应的本地 HTTP 缓存。
HttpCacheWriteBehavior	指示是否将 Windows.Web.Http 和 Windows.Web.Http.Filters 命名空间中的类方法使用的请求返回的内容写入本地 HTTP 缓存。
HttpCookieUsageBehavior	定义 CookieUsageBehavior 属性中使用的 Cookie 使用行为。

注解

Windows.Web.Http 命名空间以及相关的 Windows.Web.Http.Headers 和 Windows.Web.Http.Filters 命名空间为想要连接到 HTTP 服务的 UWP 应用提供 HTTP 编程接口。 HTTP API 为开发人员提供 JavaScript、C#、VB.NET 和 C++ 的一致支持。 API 还支持对请求和响应添加自定义筛选器。筛选器可以简化处理更复杂的网络问题。该 API 还允许应用控制读取和写入缓存行为。

Windows.Web.Http 命名空间中的类支持基于 Windows.Web.Http.Filters 命名空间中的类使用筛选器。 Windows.Web.Http.Filters 命名空间中的类还允许应用控制客户端上的读取和写入缓存行为。 Windows.Web.Http.Headers 中的 HttpCacheDirectiveHeaderValueCollection 为与 HTTP 请求或响应关联的 HTTP 内容上的 Cache-Control HTTP 标头中的缓存指令实例提供收集容器。 Cache-Control 标头允许应用更好地控制缓存行为。

Windows.Web.Http.Headers 命名空间中的类表示 IETF 在 RFC 2616 中定义的 HTTP 标头。

Windows.Web.Http 命名空间中的 HttpClient 类提供用于发送 HTTP 请求和接收 HTTP 响应的基类。筛选器提供处理程序机制来帮助解决常见的 HTTP 服务问题。简单的筛选器可以按顺序链接在一起，以处理更复杂的 HTTP 服务问题。

HTTP 筛选器是一个黑盒，它接受 HTTP 请求消息并生成 HTTP 响应消息。筛选器获取 HTTP 响应的方式由筛选器开发人员确定。筛选器通常添加或更改标头、处理授权 (可能使用 WebAuthenticationBroker) ，或者根据网络条件允许或禁止请求。筛选器通常进行更改，然后将请求传递给内部筛选器，内部筛选器通常在构造筛选器时设置。

此方法允许筛选器仅负责 HTTP 请求执行的特定方面，并将其他方面委托给其他筛选器。筛选器可以实现缓存、身份验证、重定向、Cookie、与服务器的实际通信或这些组合。最底层 (基) 筛选器通常是与网络进行实际通信的筛选器。

许多使用 HTTP 进行网络访问的应用通常需要响应各种条件。一些常见示例包括：

使用退让) 的网络重试 (。
当网络连接处于漫游状态（例如) ）时，适应按流量计费的网络 (。
向社交网站进行身份验证。
日志记录和遥测。

自行处理这些网络问题并不难。当其中几个问题组合在一起时，这将成为一个复杂的问题。支持 Windows.Web.Http.Filters 命名空间中的自定义筛选器，使开发人员能够为简单筛选器创建模块化代码。可将一系列简单的筛选器链接到筛选器链中，以处理复杂的问题组合。开发人员选择有关筛选器链的所有内容：

要添加的筛选器。
在筛选器链中放置它们的顺序。

HttpClient 是用于通过 HTTP 发送和接收请求的main类。 HttpBaseProtocolFilter 是 HttpClient 用来发送和接收数据的内容。因此，HttpBaseProtocolFilter 通常是任何自定义筛选器链的底部。 HttpBaseProtocolFilter 还可用于控制 HTTP 连接的缓存和其他行为。每个 HttpClient 实例可以具有不同的筛选器链或管道。

为了编写自定义筛选器，应用实现 IHttpFilter 接口的自定义版本。实现筛选器行为的代码位于 IHttpFilter.SendRequestAsync 方法中。可以使用 C#/VB.NET 或 C++ 编写筛选器。可以从 UWP 应用（包括 JavaScript）支持的任何语言调用和使用筛选器。

示例代码演示了一个筛选器，用于将自定义标头添加到 HTTP 请求和响应。

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);
    }
}

若要使用筛选器，应用使用 HttpClient (IHttpFilter) 构造函数传递要用于 HttpClient 实例的筛选器接口。若要设置筛选器链，新筛选器将链接到上一个筛选器，并链接到底部的 HttpBaseProtocolFilter 。

示例代码演示如何创建 HttpClient 以使用自定义筛选器。

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);

}

Windows.Web.Http.Filters 命名空间

类

接口

枚举

注解

另请参阅

反馈

反馈

其他资源