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

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

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

• Загрузить

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

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

  • Глобальная обработка ошибок
  • Улучшения маршрутизации атрибутов
  • Улучшения страницы справки
  • Поддержка IgnoreRoute
  • Форматировщик Media-Type BSON
  • Улучшенная поддержка асинхронных фильтров
  • Анализ запросов для библиотеки форматирования клиента

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

• Исправления ошибок

Скачать

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

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

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

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

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

Новые возможности в веб-API ASP.NET 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 .

Мы предоставили пример , в котором используются ограничения для динамической фильтрации контроллеров по http-заголовку api-version.

Улучшения страницы справки

Веб-API 2.1 включает следующие усовершенствования страниц справки API:

• Документация по отдельным свойствам параметров или возвращаемых типов действий.
• Документация по заметкам модели данных.

Дизайн пользовательского интерфейса страниц справки также был обновлен в соответствии с этими изменениями.

Поддержка IgnoreRoute

Веб-API 2.1 поддерживает игнорирование шаблонов URL-адресов в маршрутизации веб-API с помощью набора методов расширения IgnoreRoute в HttpRouteCollection. Эти методы приводят к тому, что веб-API игнорирует все URL-адреса, соответствующие указанному шаблону, и позволяет узлу применять дополнительную обработку, если это необходимо.

В следующем примере игнорируется URI, начинающийся с сегмента "содержимое":

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

Форматировщик Media-Type BSON

Веб-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() });

Мы предоставили пример , показывающий как клиент, так и сторону сервера.

Дополнительные сведения см. в статье Поддержка BSON в веб-API 2.1.

Улучшенная поддержка асинхронных фильтров

Веб-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 поддерживают асинхронную поддержку в веб-API 2.1.

Анализ запросов для библиотеки форматирования клиента

Ранее System.Net.Http.Formatting поддерживал анализ и обновление запросов URI для кода на стороне сервера, но в эквивалентной переносимой библиотеке эта функция отсутствовала. В веб-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

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

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

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

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

Маршрутам атрибутов запрещено использовать параметр {controller} , а также использовать параметр {action} для маршрутов, размещенных в действиях. Эти параметры, скорее всего, вызовут неоднозначность.

Формирование шаблонов MVC/Web API в проект с пакетами 5.1 приводит к тому, что пакеты 5.0 для тех, которые еще не существуют в проекте

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

Если вы используете ASP.NET формирования шаблонов после обновления пакетов до веб-API 2.1 или ASP.NET MVC 5.1, убедитесь, что версии веб-API и MVC согласованы.

Переименование типов

Некоторые типы, используемые для расширения маршрутизации атрибутов, были переименованы из версии-кандидата в RTM 2.1.

Старое имя типа (2.1 RC)	Новое имя типа (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Фильтры исключений не распаковывают агрегированные исключения, создаваемые в асинхронных действиях

Ранее, если асинхронное действие вызывало исключение AggregateException, фильтр исключений распаковывал исключение, а OnException получает базовое исключение. В версии 2.1 фильтр исключений не разворачивает его, а OnException получает исходное исключение AggregateException.

Исправления ошибок

Этот выпуск также включает несколько исправлений ошибок.

Пакет версии 5.1.2 содержит обновления IntelliSense, но не содержит исправлений ошибок.