ASP.NET Web API 2.2 的新增功能

由 Microsoft

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

• 下载

• 文档

• ASP.NET Web API 2.2 中的新功能

  • OData v4
  • 属性路由改进
  • Windows Phone 8.1 的 Web API 客户端支持

• 已知问题和中断性变更

• Bug 修复

• Microsoft.AspNet.OData 5.2.1

• Microsoft.AspNet.WebAPI 5.2.2

• Microsoft.AspNet.WebAPI 5.2.3 Beta

下载

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

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

Install-Package Microsoft.AspNet.WebApi -Version 5.2.0

文档

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

ASP.NET Web API 2.2 中的新功能

OData v4

此版本添加了对 OData v4 协议的支持。 有关详细信息，请参阅 Web API OData v4 文档。

以下是 OData v4 的一些关键功能和更改：

• 支持在 OData 模型中对属性进行别名
• 支持 ODataConventionModelBuilder 中的 ComplexTypeAttribute、AssociationAttribute、TimesTampAttribute 和 ConcurrencyCheckAttribute
• 提供为操作提供友好标题的功能
• 与 ODL UriParser 集成
• 支持枚举、 包含 和 单一实例
• 对基元类型的支持强制转换
• 添加了 OData 函数支持
• 支持函数调用的参数别名
• 支持模型中的 camel 大小写命名约定
• 支持 $filter 中的 cast ()
• 支持开放式复杂类型
• 删除了 EntitySetController 和 AsyncEntitySetController
• 已将$link更改为$ref
• 添加了属性路由支持
• 使用 OData Core 库 6.4.0

属性路由改进

属性路由现在提供一个名为 IDirectRouteProvider 的扩展点，它允许完全控制如何发现和配置属性路由。 IDirectRouteProvider 负责提供操作和控制器列表以及关联的路由信息，以指定这些操作所需的确切路由配置。 调用 MapAttributes/MapHttpAttributeRoutes 时，可以指定 IDirectRouteProvider 实现。

通过扩展默认实现 DefaultDirectRouteProvider，自定义 IDirectRouteProvider 将是最容易的。 此类提供单独的可重写虚拟方法，用于更改用于发现属性、创建路由条目和发现路由前缀和区域前缀的逻辑。

下面是一些示例，说明可对此新扩展点执行的操作：

1. 支持路由属性继承

   示例：

   此处，“/api/values/10”等请求将成功返回“Success：10”

   public class BaseController : ApiController
   {
       [Route("{id:int}")]
       public string Get(int id)
       {
           return "Success:" + id;
       }
   }
   [RoutePrefix("api/values")]
   public class ValuesController : BaseController
   {
   }
          
   config.MapHttpAttributeRoutes(new CustomDirectRouteProvider());
   public class CustomDirectRouteProvider : DefaultDirectRouteProvider
   {
       protected override IReadOnlyList<IDirectRouteFactory> 
       GetActionRouteFactories(HttpActionDescriptor actionDescriptor)
       {
           return actionDescriptor.GetCustomAttributes<IDirectRouteFactory>
           (inherit: true);
       }
   }
   

2. 遵循一些你喜欢的约定，为属性路由提供默认路由名称。 默认情况下，属性路由不会自动为属性路由创建名称。

3. 在属性路由最终出现在路由表中之前，在一个中心位置修改这些路由模板。

Windows Phone 8.1 的 Web API 客户端支持

现在，可以在面向 Windows Phone 8.1 或从通用应用内使用 Web API 客户端 NuGet 包来实现 Web API 客户端逻辑。

已知问题和中断性变更

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

OData v4

模型生成器

问题：无法将重载的函数公开为 FunctionImport

如果有 2 个重载函数，并且它们也是 FunctionImport，如下所示，则请求 ~/GetAllConventionCustomers (CustomerName={customerName}) 会导致 System.InvalidOperationException。

<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true" />
<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true">
<Parameter Name="CustomerName" Type="Edm.String" FixedLength="false" 
Unicode="false" />
</Function>
...
<FunctionImport Name="GetAllConventionCustomers" 
Function="WebStack.QA.Test.OData.UnboundOperation.GetAllConventionCustomers" 
EntitySet="ConventionCustomers" IncludeInServiceDocument="true" />

解决方法：此问题的解决方法是将两个函数重载添加为 FunctionImports。

OData 路由

在 OData 资源路径中使用时，包含 URL 编码斜杠 (%2F) 和反斜杠 (%5C) 的字符串文本会导致 404 错误。

例如，字符串文本可以在 OData 资源路径中用作实体集的函数或键值的参数。

/Employees/Total.GetCount (Name='Name%2F')

/Employees ('Name%5C')

当服务收到此类请求时，主机将在将转义序列传递到 Web API 运行时之前取消转义这些转义序列。 这可以防止以下攻击：

http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:

这会导致 Web API OData 堆栈返回 404 错误 (找不到) 。 若要防止此错误，客户端应对斜杠 (%252F) 使用双转义序列和反斜杠 (%255C) 。 对于 /Employees？$filter=Name eq 'Name%2F' 等查询字符串，不会发生这种情况

请注意，非转义斜杠 ('/') 和反斜杠 ('') 在 OData 资源路径字符串文本中是不合法的。 斜杠应仅显示为路径分隔符，而反斜杠根本不应出现在 OData 资源路径中。 (两者在 OData 查询字符串的某些部分都可用。)

解决方法：在实际分析字符串文本之前，可以重写 DefaultODataPathHandler 的 Parse 方法，以转义字符串文本中的斜杠和反斜杠。 可在此处找到此方法的示例。

OData v3

[可查询]

[Queryable] 属性已弃用。 新的 OData v3 应用程序应使用 System.Web.Http.OData.EnableQueryAttribute。

ODataHttpConfigurationExtensions.EnableQuerySupport 扩展方法现在将 EnableQueryAttribute 添加到全局筛选器集合。 如果任何控制器具有 [Queryable] 属性，则调用 config.EnableQuerySupport() 将导致 [Queryable] 属性失败

解决此问题的建议方法是将 QueryableAttribute 的所有实例替换为 System.Web.Http.OData.EnableQueryAttribute。

另一种解决方法是在 Web API 配置中使用以下代码：

config.EnableQuerySupport(new QueryableAttribute());

属性路由

问题：使用属性路由时，使用 FromUri 属性修饰的复杂类型的模型绑定的行为不同。

问题：将 MVC/Web API 基架到具有 5.2.0 包的项目会导致项目中尚不存在的包产生 5.1.2 个包

更新 ASP.NET MVC 5.2 的 NuGet 包不会更新 Visual Studio 工具，例如 ASP.NET 基架或 ASP.NET Web 应用程序项目模板。 它们使用以前版本的 ASP.NET 运行时包 (，例如 Update 2) 中的 5.1.2。 因此，ASP.NET 基架将安装以前的版本 (例如 Update 2 中的 5.1.2) 所需包（如果这些版本在项目中尚不可用）。 但是，Visual Studio 2013 RTM 或 Update 1 中的 ASP.NET 基架不会覆盖项目中的最新包。 如果在将项目的包更新到 Web API 2.2 或 ASP.NET MVC 5.2 后使用 ASP.NET 基架，请确保 Web API 和 ASP.NET MVC 的版本一致。

Microsoft.AspNet.OData 5.2.1

Microsoft.AspNet.OData 5.2.1 包包含 NuGet 依赖项更新，但没有 bug 修复。 通过此更新，不再严格依赖 Microsoft.OData.Core 6.4.0，但可以升级到 6.4.0 和 7.0.0 之间的任何版本。

Microsoft.AspNet.WebAPI 5.2.2

在此版本中，我们已对 Json.Net 6.0.4进行了依赖项更改。 有关此版本的 中的 Json.NET新增功能的详细信息，请参阅 Json.NET 6.0 版本 4 - JSON 合并、依赖关系注入。 此版本在 Web API 中没有任何其他新功能或 bug 修复。 我们随后更新了我们拥有的所有其他依赖包，以依赖于此新版本的 Web API。

Microsoft.AspNet.WebAPI 5.2.3 Beta

可 在此处阅读有关版本的信息。 此版本仅包含 bug 修复。