ASP.NET Web API 2.2 的新增功能

  • 项目

由 Microsoft

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

下载

运行时功能作为 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 的一些关键功能和更改：

属性路由改进

属性路由现在提供一个名为 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 修复。