Novidades no ASP.NET Web API 2.1

pela Microsoft

Este tópico descreve as novidades do ASP.NET Web API 2.1.

• Download

• Documentação

• Novos recursos no ASP.NET Web API 2.1

  • Tratamento global de erros
  • Aprimoramentos de roteamento de atributo
  • Aprimoramentos da Página de Ajuda
  • Suporte a IgnoreRoute
  • Formatador de Media-Type BSON
  • Melhor suporte para filtros assíncronos
  • Análise de consulta para a biblioteca de formatação do cliente

• Problemas conhecidos e alterações interruptivas

• Correções de bug

Baixar

Os recursos de runtime são lançados como pacotes NuGet na galeria do NuGet. Todos os pacotes de runtime seguem a especificação controle de versão semântico . O pacote RTM mais recente ASP.NET Web API 2.1 tem a seguinte versão: "5.1.2". Você pode instalar ou atualizar esses pacotes por meio do NuGet. A versão também inclui pacotes localizados correspondentes no NuGet.

Você pode instalar ou atualizar para os pacotes NuGet lançados usando o Console do Gerenciador de Pacotes NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Documentação

Tutoriais e outras informações sobre ASP.NET Web API RTM 2.1 estão disponíveis no site do ASP.NET (https://www.asp.net/web-api).

Novos recursos no ASP.NET Web API 2.1

Tratamento global de erros

Todas as exceções sem tratamento agora podem ser registradas por meio de um mecanismo central, e o comportamento de exceções sem tratamento pode ser personalizado.

A estrutura dá suporte a vários agentes de exceção, que todos veem a exceção sem tratamento e informações sobre o contexto em que ela ocorreu, como a solicitação que está sendo processada no momento.

Por exemplo, o código a seguir usa System.Diagnostics.TraceSource para registrar todas as exceções sem tratamento:

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

Você também pode substituir o manipulador de exceção padrão, para que você possa personalizar totalmente a mensagem de resposta HTTP que é enviada quando ocorre uma exceção sem tratamento.

Fornecemos um exemplo que registra todas as exceções sem tratamento por meio da estrutura ELMAH popular.

Aprimoramentos de roteamento de atributo

O roteamento de atributo agora dá suporte a restrições, habilitando o controle de versão e a seleção de rota baseada em cabeçalho. Além disso, muitos aspectos das rotas de atributo agora são personalizáveis por meio da interface IDirectRouteFactory e da classe RouteFactoryAttribute . O prefixo de rota agora é extensível por meio da interface IRoutePrefix e da classe RoutePrefixAttribute .

Fornecemos um exemplo que usa restrições para filtrar dinamicamente controladores por um cabeçalho HTTP 'api-version'.

Aprimoramentos da Página de Ajuda

A API Web 2.1 inclui os seguintes aprimoramentos nas Páginas de Ajuda da API:

• Documentação de propriedades individuais de parâmetros ou tipos de retorno de ações.
• Documentação de anotações de modelo de dados.

O design da interface do usuário das páginas de ajuda também foi atualizado para acomodar essas alterações.

Suporte a IgnoreRoute

A API Web 2.1 dá suporte a ignorar padrões de URL no roteamento de API Web por meio de um conjunto de métodos de extensão IgnoreRoute em HttpRouteCollection. Esses métodos fazem com que a API Web ignore todas as URLs que correspondam a um modelo especificado e permitam que o host aplique processamento adicional, se apropriado.

O exemplo a seguir ignora URIs que começam com um segmento de "conteúdo":

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

Formatador de Media-Type BSON

A API Web agora dá suporte ao formato de transmissão BSON , tanto no cliente quanto no servidor.

Para habilitar o BSON no lado do servidor, adicione o BsonMediaTypeFormatter à coleção formatadores:

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

Veja como um cliente .NET pode consumir o 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() });

Fornecemos um exemplo que mostra o lado do cliente e do servidor.

Para obter mais informações, consulte Suporte a BSON na API Web 2.1

Melhor suporte para filtros assíncronos

A API Web agora dá suporte a uma maneira fácil de criar filtros que são executados de forma assíncrona. Esse recurso é útil porque o filtro precisa executar uma ação assíncrona, como acessar um banco de dados. Anteriormente, para criar um filtro assíncrono, você precisava implementar a interface de filtro por conta própria, pois as classes base de filtro expunguiam apenas métodos síncronos. Agora você pode substituir os métodos virtuais On*Async da classe base de filtro.

Por exemplo:

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

As classes AuthorizationFilterAttribute, ActionFilterAttribute e ExceptionFilterAttribute dão suporte a assíncrona na API Web 2.1.

Análise de consulta para a biblioteca de formatação do cliente

Anteriormente, System.Net.Http.Formatting tinha suporte para análise e atualização de consultas de URI para código do lado do servidor, mas a biblioteca portátil equivalente não tinha esse recurso. Na API Web 2.1, um aplicativo cliente agora pode analisar e atualizar facilmente uma cadeia de caracteres de consulta.

Os exemplos a seguir mostram como analisar, modificar e gerar consultas de URI. (Os exemplos mostram um aplicativo de console 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 conhecidos e alterações interruptivas

Esta seção descreve problemas conhecidos e alterações interruptivas no RTM ASP.NET Web API 2.1.

Roteamento de atributo

Ambiguidades em correspondências de roteamento de atributo agora relatam um erro em vez de escolher a primeira correspondência.

As rotas de atributo são proibidas de usar o parâmetro {controller} e de usar o parâmetro {action} em rotas colocadas em ações. Esses parâmetros provavelmente causariam ambiguidades.

O scaffolding de MVC/API Web em um projeto com pacotes 5.1 resulta em pacotes 5.0 para os que ainda não existem no projeto

A atualização de pacotes NuGet para ASP.NET Web API 2.1 RTM não atualiza as ferramentas do Visual Studio, como ASP.NET scaffolding ou o modelo de projeto de aplicativo Web ASP.NET. Eles usam a versão anterior do ASP.NET pacotes de runtime (5.0.0.0). Como resultado, o scaffolding ASP.NET instalará a versão anterior (5.0.0.0) dos pacotes necessários, se eles ainda não estiverem disponíveis em seus projetos. No entanto, o ASP.NET scaffolding no Visual Studio 2013 RTM ou na Atualização 1 não substitui os pacotes mais recentes em seus projetos.

Se você usar ASP.NET scaffolding depois de atualizar os pacotes para a API Web 2.1 ou ASP.NET MVC 5.1, verifique se as versões da API Web e do MVC são consistentes.

Renomeações de tipo

Alguns dos tipos usados para extensibilidade de roteamento de atributo foram renomeados do RC para o RTM 2.1.

Nome do tipo antigo (2.1 RC)	Novo nome de tipo (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Os filtros de exceção não desencapsulam exceções de agregação geradas em ações assíncronas

Anteriormente, se uma ação assíncrona gerasse uma AggregateException, um filtro de exceção desembrulharia a exceção e OnException obteria a exceção base. Na versão 2.1, o filtro de exceção não o desencapsula e OnException obtém a AggregateException original.

Correções de bugs

Esta versão também inclui várias correções de bugs.

O pacote 5.1.2 contém atualizações do IntelliSense, mas nenhuma correção de bug.