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.

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.