Поделиться через

Новые возможности веб-API ASP.NET 2.2

  • Статья

от Корпорации Майкрософт

В этом разделе описываются новые возможности веб-API ASP.NET 2.2.

Скачать

Функции среды выполнения выпускаются в виде пакетов NuGet в коллекции NuGet. Все пакеты среды выполнения соответствуют спецификации семантического управления версиями . Последняя версия пакета веб-API ASP.NET 2.2 имеет следующую версию: "5.2.0". Эти пакеты можно установить или обновить с помощью NuGet. Выпуск также включает соответствующие локализованные пакеты в NuGet.

Вы можете установить или обновить выпущенные пакеты NuGet с помощью консоли диспетчера пакетов NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.2.0

Документация

Руководства и другие сведения о веб-API ASP.NET 2.2 доступны на веб-сайте ASP.NET (https://www.asp.net/web-api).

Новые возможности в веб-API ASP.NET 2.2

OData v4

В этом выпуске добавлена поддержка протокола OData версии 4. Дополнительные сведения см. в документации по веб-API OData версии 4.

Ниже приведены некоторые ключевые функции и изменения для OData версии 4.

Улучшения маршрутизации атрибутов

Маршрутизация атрибутов теперь предоставляет точку расширяемости IDirectRouteProvider, которая позволяет полностью контролировать обнаружение и настройку маршрутов атрибутов. IDirectRouteProvider отвечает за предоставление списка действий и контроллеров вместе со связанными сведениями о маршруте, чтобы указать, какая именно конфигурация маршрутизации требуется для этих действий. Реализация IDirectRouteProvider может быть указана при вызове MapAttributes/MapHttpAttributeRoutes.

Настроить IDirectRouteProvider будет проще всего, расширив реализацию по умолчанию DefaultDirectRouteProvider. Этот класс предоставляет отдельные переопределяемые виртуальные методы для изменения логики обнаружения атрибутов, создания записей маршрута и обнаружения префикса маршрута и префикса области.

Ниже приведены некоторые примеры того, что можно сделать с этой новой точкой расширяемости.

  1. Поддержка наследования атрибутов route

    Пример

    Здесь запрос, например /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. Измените шаблон маршрутов атрибутов в одном центральном месте, прежде чем они поместятся в таблицу маршрутов.

Поддержка клиентов веб-API для Windows Phone 8.1

Теперь вы можете использовать пакет NuGet клиента веб-API для реализации логики клиента веб-API при выборе Windows Phone 8.1 или из универсального приложения.

Известные проблемы и критические изменения

В этом разделе описываются известные проблемы и критические изменения в веб-API ASP.NET 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

Строковые литералы, включающие косую черту в кодировке URL-адреса (%2F) и обратную косую черту (%5C), вызывают ошибку 404 при использовании в путях к ресурсам OData.

Например, строковые литералы можно использовать в путях к ресурсам OData в качестве параметров функций или значений ключей наборов сущностей.

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

/Employees('Name%5C')

Когда службы получают такие запросы, узлы отменяют экранирование этих escape-последовательностей перед их передачей в среду выполнения веб-API. Это обеспечивает защиту от атак, подобных следующим:

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

Это приводит к тому, что стек OData веб-API возвращает ошибку 404 (Не найдено). Чтобы избежать этой ошибки, клиент должен использовать двойные escape-последовательности для косой черты (%252F) и обратной косой черты (%255C). Это не происходит для строк запроса, таких как /Employees?$filter=Name eq 'Name%2F'

Обратите внимание, что косая черта без экранирования ('/') и обратная косая черта ('') не являются допустимыми в строковых литералах пути к ресурсу OData. Косая черта должна отображаться только как разделители пути, а обратная косая черта не должна отображаться в пути к ресурсу OData. (Оба варианта можно использовать в некоторых фрагментах строки запроса OData.)

Обходной путь. Вы можете переопределить метод Parse DefaultODataPathHandler, чтобы экранировать косую черту и обратную косую черту в строковых литералах перед фактическим их анализом. Пример этого подхода можно найти здесь.

OData v3

[Доступный для запроса]

Атрибут [Queryable] является устаревшим. Новые приложения OData версии 3 должны использовать System.Web.Http.OData.EnableQueryAttribute.

Метод расширения ODataHttpConfigurationExtensions.EnableQuerySupport теперь добавляет атрибут EnableQueryAttribute в глобальную коллекцию фильтров. Если какой-либо контроллер имеет атрибут [Запрашиваемый], вызов config.EnableQuerySupport() приведет к сбою атрибута [Запрашиваемый]

Для устранения этой проблемы рекомендуется заменить все экземпляры QueryableAttributeна System.Web.Http.OData.EnableQueryAttribute.

Альтернативным решением является использование следующего кода в конфигурации веб-API:

config.EnableQuerySupport(new QueryableAttribute());

Маршрутизация атрибутов

Проблема. При использовании маршрутизации атрибутов привязка модели сложного типа, декорированная атрибутом FromUri, ведет себя по-разному.

Проблема. Формирование шаблонов MVC/Web API в проект с пакетами 5.2.0 приводит к созданию пакетов 5.1.2 для тех, которые еще не существуют в проекте

Обновление пакетов NuGet для ASP.NET MVC 5.2 не обновляет средства Visual Studio, такие как ASP.NET формирование шаблонов или шаблон проекта веб-приложения ASP.NET. Они используют предыдущую версию пакетов среды выполнения ASP.NET (например, 5.1.2 в обновлении 2). В результате ASP.NET формирования шаблонов установит предыдущую версию (например, 5.1.2 в обновлении 2) необходимых пакетов, если они еще не доступны в ваших проектах. Однако ASP.NET формирования шаблонов в Visual Studio 2013 RTM или обновлении 1 не перезаписывают последние пакеты в проектах. Если вы используете ASP.NET формирования шаблонов после обновления пакетов проектов до веб-API 2.2 или ASP.NET MVC 5.2, убедитесь, что версии веб-API и ASP.NET MVC согласованы.

Microsoft.AspNet.OData 5.2.1

Пакет Microsoft.AspNet.OData 5.2.1 содержит обновления зависимостей NuGet, но не содержит исправлений ошибок. В этом обновлении больше нет строгой зависимости от 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, внедрение зависимостей. В этом выпуске нет других новых функций или исправлений ошибок в веб-API. Впоследствии мы обновили все остальные зависимые пакеты, в которых мы владеем, чтобы они зависели от этой новой версии веб-API.

Microsoft.AspNet.WebAPI 5.2.3 (бета-версия)

Вы можете прочитать о выпуске здесь. Этот выпуск содержит только исправления ошибок.