Novedades de ASP.NET Web API 2.1

por Microsoft

En este tema, se describen las novedades de ASP.NET Web API 2.1.

• Descargar

• Documentación

• Nuevas características de ASP.NET Web API 2.1

  • Control de errores global
  • Mejoras en el enrutamiento de atributos
  • Mejoras en la página de ayuda
  • Compatibilidad con IgnoreRoute
  • Formateador de tipo multimedia de BSON
  • Mejor compatibilidad con filtros asincrónicos
  • Análisis de consultas para la biblioteca de formato de cliente

• Problemas conocidos y cambios importantes

• Correcciones de errores

Descargar

Las características en tiempo de ejecución se publican como paquetes NuGet en la galería de NuGet. Todos los paquetes en tiempo de ejecución siguen la especificación de Versionamiento Semántico. El paquete ASP.NET Web API 2.1 RTM más reciente tiene la siguiente versión: "5.1.2". Puede instalar o actualizar estos paquetes mediante NuGet. La versión también incluye los paquetes localizados correspondientes en NuGet.

Puede instalar o actualizar los paquetes NuGet publicados mediante la consola del Administrador de paquetes NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Documentación

Los tutoriales y otra información sobre ASP.NET Web API 2.1 RTM están disponibles en el sitio web de ASP.NET ( https://www.asp.net/web-api).

Nuevas características de ASP.NET Web API 2.1

Control de errores global

Todas las excepciones no controladas ahora se pueden registrar a través de un mecanismo central y se puede personalizar el comportamiento de las excepciones no controladas.

El marco admite varios registradores de excepciones, que ven la excepción no controlada e información sobre el contexto en el que se produjo, como la solicitud que se está procesando en el momento.

Por ejemplo, el código siguiente usa System.Diagnostics.TraceSource para registrar todas las excepciones no controladas:

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)));

También puede reemplazar el controlador de excepciones predeterminado, de modo que pueda personalizar completamente el mensaje de respuesta HTTP que se envía cuando se produce una excepción no controlada.

Hemos proporcionado un ejemplo que registra todas las excepciones no controladas a través del popular marco ELMAH.

Mejoras en el enrutamiento de atributos

El enrutamiento de atributos ahora admite restricciones, lo que permite el control de versiones y la selección de rutas basada en encabezados. Además, muchos aspectos de las rutas de atributo ahora se pueden personalizar a través de la interfaz IDirectRouteFactory y la clase RouteFactoryAttribute. El prefijo de ruta ahora es extensible a través de la interfaz IRoutePrefix y la clase RoutePrefixAttribute.

Hemos proporcionado un ejemplo que usa restricciones para filtrar dinámicamente los controladores mediante un encabezado HTTP "api-version".

Mejoras en la página de ayuda

Web API 2.1 incluye las siguientes mejoras en las páginas de ayuda de API:

• Documentación de propiedades individuales de parámetros o tipos devueltos de acciones.
• Documentación de anotaciones del modelo de datos.

El diseño de la interfaz de usuario de las páginas de ayuda también se actualizó para dar cabida a estos cambios.

Compatibilidad con IgnoreRoute

Web API 2.1 admite la omisión de patrones de dirección URL en el enrutamiento de Web API, a través de un conjunto de métodos de extensión IgnoreRoute en HttpRouteCollection. Estos métodos hacen que la Web API omita las direcciones URL que coincidan con una plantilla especificada y permita que el host aplique procesamiento adicional si procede.

En el ejemplo siguiente se omiten los URI que comienzan con un segmento de "contenido":

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

Formateador de tipo multimedia de BSON

La Web API ahora admite el formato de conexión BSON, tanto en el cliente como en el servidor.

Para habilitar BSON en el servidor, agregue BsonMediaTypeFormatter a la colección de formateadores:

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

Este es el modo en el que un cliente .NET puede consumir el formato 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() });

Hemos proporcionado un ejemplo que muestra tanto el cliente como el lado servidor.

Para obtener más información, consulte Compatibilidad con BSON en Web API 2.1

Mejor compatibilidad con filtros asincrónicos

La Web API ahora admite una manera sencilla de crear filtros que se ejecutan de forma asincrónica. Para que esta característica sea útil, el filtro debe realizar una acción asincrónica, como acceder a una base de datos. Anteriormente, para crear un filtro asincrónico, tenía que implementar la interfaz de filtro usted mismo, ya que las clases base de filtro solo exponen métodos sincrónicos. Ahora puede invalidar los métodos virtuales On*Async de la clase base de filtro.

Por ejemplo:

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

Las clases AuthorizationFilterAttribute, ActionFilterAttribute y ExceptionFilterAttribute admiten async en Web API 2.1.

Análisis de consultas para la biblioteca de formato de cliente

Anteriormente, System.Net.Http.Format admitía el análisis y la actualización de consultas de URI para el código del lado servidor, pero faltaba esta característica en la biblioteca portable equivalente. En Web API 2.1, una aplicación cliente ahora puede analizar y actualizar fácilmente una cadena de consulta.

En los ejemplos siguientes se muestra cómo analizar, modificar y generar consultas de URI. (Los ejemplos muestran una aplicación de consola para simplificar).

// 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

Problemas conocidos y cambios importantes

En esta sección, se describen los problemas conocidos y los cambios importantes en ASP.NET Web API 2.1 RTM.

Enrutamiento de atributos

Las ambigüedades en las coincidencias de enrutamiento de atributos ahora notificarán un error en lugar de elegir la primera coincidencia.

Las rutas de atributo tienen prohibido usar el parámetro {controller} y usar el parámetro {action} en las rutas realizadas en acciones. Estos parámetros probablemente causarían ambigüedades.

Aplicar scaffolding MVC/Web API a un proyecto con paquetes 5.1 da como resultado paquetes 5.0 para los que aún no existen en el proyecto

La actualización de paquetes NuGet para ASP.NET Web API 2.1 RTM no actualiza las herramientas de Visual Studio, como el scaffolding de ASP.NET o la plantilla de proyecto de aplicación web de ASP.NET. Usan la versión anterior de los paquetes en tiempo de ejecución de ASP.NET (5.0.0.0). Como resultado, el scaffolding de ASP.NET instalará la versión anterior (5.0.0.0) de los paquetes necesarios, si aún no están disponibles en los proyectos. Sin embargo, el scaffolding de ASP.NET en Visual Studio 2013 RTM o la actualización 1 no sobrescribe los paquetes más recientes de los proyectos.

Si usa el scaffolding de ASP.NET después de actualizar los paquetes de los proyectos a Web API 2.1 o ASP.NET MVC 5.1, asegúrese de que las versiones de Web API y ASP.NET MVC sean coherentes.

Cambio de nombre de tipo

Algunos de los tipos usados para la extensibilidad de enrutamiento de atributos se cambiaron de RC a RTM 2.1.

Nombre de tipo antiguo (2.1 RC)	Nuevo nombre de tipo (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Los filtros de excepción no desencapsulan las excepciones agregadas producidas en acciones asincrónicas

Anteriormente, si una acción asincrónica produjo un AggregateException, un filtro de excepción desencapsularía la excepción y OnException obtendría la excepción base. En la versión 2.1, el filtro de excepciones no lo desencapsula y OnException obtiene el AggregateException original.

Correcciones de errores

Esta versión también incluye varias correcciones de errores.

El paquete 5.1.2 contiene actualizaciones de IntelliSense, pero no correcciones de errores.