ASP.NET Web API 2.1 的新增功能

项目
06/25/2023

本主题介绍 ASP.NET Web API 2.1 的新增功能。

下载
文档
ASP.NET Web API 2.1 中的新增功能
已知问题和重大更改
Bug 修复

下载

运行时功能作为 NuGet 库上的 NuGet 包发布。所有运行时包都遵循语义版本控制规范。最新的 ASP.NET Web API 2.1 RTM 包具有以下版本：“5.1.2”。可以通过 NuGet 安装或更新这些包。该版本还包括 NuGet 上的相应本地化包。

可以使用 NuGet 包管理器控制台安装或更新已发布的 NuGet 包：

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

文档

有关 ASP.NET Web API 2.1 RTM 的教程和其他信息，请参阅 ASP.NET 网站 (https://www.asp.net/web-api) 。

ASP.NET Web API 2.1 中的新增功能

全局错误处理

现在可以通过一个中心机制记录所有未经处理的异常，并且可以自定义未经处理的异常的行为。

框架支持多个异常记录器，所有这些异常记录器都可以看到未经处理的异常以及有关发生异常的上下文的信息，例如当时正在处理的请求。

例如，以下代码使用 System.Diagnostics.TraceSource 记录所有未经处理的异常：

public class TraceSourceExceptionLogger : ExceptionLogger
{
    private readonly TraceSource _traceSource;

    public TraceSourceExceptionLogger(TraceSource traceSource)
    {
        _traceSource = traceSource;
    }

    public override void Log(ExceptionLoggerContext context)
    {
        _traceSource.TraceEvent(TraceEventType.Error, 1,
            "Unhandled exception processing {0} for {1}: {2}",
            context.Request.Method,
            context.Request.RequestUri,
            context.Exception);
    }
}

config.Services.Add(typeof(IExceptionLogger), 
    new TraceSourceExceptionLogger(new 
    TraceSource("MyTraceSource", SourceLevels.All)));

还可以替换默认异常处理程序，以便完全自定义发生未经处理的异常时发送的 HTTP 响应消息。

我们提供了一个示例，该示例通过常用的 ELMAH 框架记录所有未经处理的异常。

属性路由改进

属性路由现在支持约束，从而启用版本控制以及基于标头的路由选择。此外，现在可以通过 IDirectRouteFactory 接口和 RouteFactoryAttribute 类自定义属性路由的许多方面。路由前缀现在可通过 IRoutePrefix 接口和 RoutePrefixAttribute 类进行扩展。

我们提供了一个示例，该示例使用约束通过“api-version”HTTP 标头动态筛选控制器。

帮助页改进

Web API 2.1 包括 API 帮助页的以下增强功能：

参数的各个属性或返回操作类型的文档。
数据模型注释的文档。

帮助页的 UI 设计也进行了更新，以适应这些更改。

IgnoreRoute 支持

Web API 2.1 支持通过 HttpRouteCollection 上的一组 IgnoreRoute 扩展方法在 Web API 路由中忽略 URL 模式。这些方法会导致 Web API 忽略与指定模板匹配的任何 URL，并允许主机应用其他处理（如果适用）。

以下示例忽略以“内容”段开头的 URI：

routes.IgnoreRoute("IgnoreContent", "content/{*paths}");
routes.MapHttpRoute("Default", "{controller}/{id}");

BSON Media-Type格式化程序

Web API 现在在客户端和服务器上都支持 BSON 线路格式。

若要在服务器端启用 BSON，请将 BsonMediaTypeFormatter 添加到格式化程序集合：

config.Formatters.Add(new BsonMediaTypeFormatter());

下面是 .NET 客户端使用 BSON 格式的方式：

// Add Accept header.
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/bson"));

// POST data in BSON format.
HttpResponseMessage response = await client.PostAsync<MyData>("api/MyData", data, new 
BsonMediaTypeFormatter());

// GET data in BSON format.
data = await response.Content.ReadAsAsync<MyData>(new MediaTypeFormatter[] { 
  new BsonMediaTypeFormatter() });

我们提供了一个同时显示客户端和服务器端的示例。

有关详细信息，请参阅 Web API 2.1 中的 BSON 支持

对异步筛选器的更好支持

Web API 现在支持创建异步执行的筛选器的简单方法。如果筛选器需要执行异步操作（例如访问数据库），此功能非常有用。以前，若要创建异步筛选器，必须自行实现筛选器接口，因为筛选器基类仅公开同步方法。现在可以替代筛选器基类的虚拟 On*Async 方法。

例如：

public class AsyncLoggingFilter : ActionFilterAttribute
{
    public override async Task OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken cancellationToken)
    {
        await Trace.WriteAsync("Executing action named {0} for request {1}.", 
            actionContext.ActionDescriptor.ActionName, 
            actionContext.Request.GetCorrelationId());
    }
}

AuthorizationFilterAttribute、ActionFilterAttribute 和 ExceptionFilterAttribute 类都支持 Web API 2.1 中的异步。

客户端格式库的查询分析

以前， System.Net.Http.Formatting 支持分析和更新服务器端代码的 URI 查询，但等效的可移植库缺少此功能。在 Web API 2.1 中，客户端应用程序现在可以轻松分析和更新查询字符串。

以下示例演示如何分析、修改和生成 URI 查询。 (为简单起见，这些示例演示了控制台应用程序。)

// Query parsing
HttpValueCollection collection = new Uri("http://api/something?catId=3&catId=4&dogId=1,2").ParseQueryString();

Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2

// Modify the query
collection.Add("dogId", "7");

// Index into the values
Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2,7

// Recreate the query string
Console.WriteLine(collection.ToString()); // output: catId=3&catId=4&dogId=1%2C2&dogId=7

// Query generation
HttpValueCollection newCollection = new HttpValueCollection();

newCollection.Add("catId", "1");
newCollection.Add("dogId", "7");

// Index into the values
Console.WriteLine(newCollection["catId"]); // output: 1
Console.WriteLine(newCollection["dogId"]); // output: 7

// Create the query string
Console.WriteLine(newCollection.ToString()); // catId=1&dogId=7

已知问题和重大更改

本部分介绍 ASP.NET Web API 2.1 RTM 中的已知问题和中断性变更。

属性路由

属性路由匹配中的多义性现在报告错误，而不是选择第一个匹配项。

属性路由被禁止使用 {controller} 参数，以及禁止在操作上放置的路由上使用 {action} 参数。这些参数极有可能导致歧义。

将 MVC/Web API 搭建基架到具有 5.1 包的项目会导致项目中尚不存在的包生成 5.0 个包

更新 ASP.NET Web API 2.1 RTM 的 NuGet 包不会更新 Visual Studio 工具，例如 ASP.NET 基架或 ASP.NET Web 应用程序项目模板。它们使用以前版本的 ASP.NET 运行时包 (5.0.0.0) 。因此，ASP.NET 基架将安装以前版本 (5.0.0.0) 所需包（如果它们在项目中尚不可用）。但是，Visual Studio 2013 RTM 或 Update 1 中的 ASP.NET 基架不会覆盖项目中的最新包。

如果在将包更新到 Web API 2.1 或 ASP.NET MVC 5.1 后使用 ASP.NET 基架，请确保 Web API 和 MVC 的版本一致。

类型重命名

用于属性路由扩展性的一些类型已从 RC 重命名为 2.1 RTM。

旧类型名称 (2.1 RC)	(2.1 RTM) 的新类型名称
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

异常筛选器不会解包异步操作中引发的聚合异常

以前，如果异步操作引发了 AggregateException，则异常筛选器将解包该异常， OnException 将获取基本异常。在 2.1 中，异常筛选器不会将其解包， 并且 OnException 获取原始 AggregateException。

Bug 修复

此版本还包括多个 bug 修复。

5.1.2 包包含 IntelliSense 更新，但没有 bug 修复。