Configurando o ASP.NET Web API 2

por Mike Wasson

Este tópico descreve como configurar ASP.NET Web API.

Definições de configuração

As definições de configuração da API Web são definidas na classe HttpConfiguration .

Membro DESCRIÇÃO
DependencyResolver Habilita a injeção de dependência para controladores. Consulte usando o resolvedor de dependência da API Web.
Filtros Filtros de ação.
Formatadores Formatadores de tipo de mídia.
IncludeErrorDetailPolicy Especifica se o servidor deve incluir detalhes do erro, como mensagens de exceção e rastreamentos de pilha, em mensagens de resposta HTTP. Consulte IncludeErrorDetailPolicy.
Inicializador Uma função que executa a inicialização final do HttpConfiguration.
MessageHandlers Manipuladores de mensagens http.
ParameterBindingRules Uma coleção de regras para parâmetros de associação em ações do controlador.
Propriedades Um recipiente de propriedades genérico.
Rotas A coleção de rotas. Consulte Roteamento em ASP.NET Web API.
Serviços A coleção de serviços. Consulte Serviços.

Prerequisites

Visual Studio 2017 Community, Professional ou Enterprise Edition.

Configurando a API Web com hospedagem ASP.NET

Em um aplicativo ASP.NET, configure a API da Web chamando GlobalConfiguration. Configure no método Start do aplicativo_ . O método Configure usa um delegado com um único parâmetro do tipo HttpConfiguration. Execute toda a sua configuração dentro do delegado.

Veja um exemplo de como usar um delegado anônimo:

using System.Web.Http;
namespace WebApplication1
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            GlobalConfiguration.Configure(config =>
            {
                config.MapHttpAttributeRoutes();

                config.Routes.MapHttpRoute(
                    name: "DefaultApi",
                    routeTemplate: "api/{controller}/{id}",
                    defaults: new { id = RouteParameter.Optional }
                );
            });
        }
    }
}

No Visual Studio 2017, o modelo de projeto "aplicativo Web ASP.NET" configura automaticamente o código de configuração, se você selecionar "API Web" na caixa de diálogo novo projeto ASP.net .

O modelo de projeto cria um arquivo chamado WebApiConfig.cs dentro do aplicativo_pasta inicial. Esse arquivo de código define o delegado em que você deve colocar o código de configuração da API Web.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebApplication1
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // TODO: Add any additional configuration code.

            // Web API routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

O modelo de projeto também adiciona o código que chama o delegado do aplicativo_iniciar.

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
    }
}

Configurando a API Web com hospedagem interna OWIN

Se você estiver hospedando internamente com o OWIN, crie uma nova instância do HttpConfiguration . Execute qualquer configuração nessa instância e, em seguida, passe a instância para o método de extensão Owin. UseWebApi .

public class Startup 
{ 
    public void Configuration(IAppBuilder appBuilder) 
    { 
        HttpConfiguration config = new HttpConfiguration(); 

        config.Routes.MapHttpRoute( 
            name: "DefaultApi", 
            routeTemplate: "api/{controller}/{id}", 
            defaults: new { id = RouteParameter.Optional } 
        ); 

        appBuilder.UseWebApi(config); 
    } 
}

O tutorial usar OWIN para auto-Host ASP.NET Web API 2 mostra as etapas completas.

Serviços de API Web globais

A coleção HttpConfiguration. Services contém um conjunto de serviços globais que a API da Web usa para executar várias tarefas, como a seleção de controlador e a negociação de conteúdo.

Note

A coleção de Serviços não é um mecanismo de finalidade geral para descoberta de serviço ou injeção de dependência. Ele armazena apenas os tipos de serviço que são conhecidos pela estrutura da API Web.

A coleção de Serviços é inicializada com um conjunto padrão de serviços e você pode fornecer suas próprias implementações personalizadas. Alguns serviços dão suporte a várias instâncias, enquanto outros podem ter apenas uma instância. (No entanto, você também pode fornecer serviços no nível do controlador; consulte configuração por controlador.

Serviços de instância única

Serviço DESCRIÇÃO
IActionValueBinder Obtém uma associação para um parâmetro.
IApiExplorer Obtém descrições das APIs expostas pelo aplicativo. Consulte criando uma página de ajuda para uma API da Web.
IAssembliesResolver Obtém uma lista dos assemblies para o aplicativo. Consulte seleção de roteamento e ação.
IBodyModelValidator Valida um modelo que é lido a partir do corpo da solicitação por um formatador de tipo de mídia.
IContentNegotiator Realiza a negociação de conteúdo.
IDocumentationProvider Fornece documentação para APIs. O padrão é nulo. Consulte criando uma página de ajuda para uma API da Web.
IHostBufferPolicySelector Indica se o host deve armazenar em buffer os corpos de entidade de mensagem HTTP.
IHttpActionInvoker Invoca uma ação do controlador. Consulte seleção de roteamento e ação.
IHttpActionSelector Seleciona uma ação do controlador. Consulte seleção de roteamento e ação.
IHttpControllerActivator Ativa um controlador. Consulte seleção de roteamento e ação.
IHttpControllerSelector Seleciona um controlador. Consulte seleção de roteamento e ação.
IHttpControllerTypeResolver Fornece uma lista dos tipos de controlador da API Web no aplicativo. Consulte seleção de roteamento e ação.
ITraceManager Inicializa a estrutura de rastreamento. Consulte rastreamento em ASP.NET Web API.
ITraceWriter Fornece um gravador de rastreamento. O padrão é um gravador de rastreamento "não op". Consulte rastreamento em ASP.NET Web API.
IModelValidatorCache Fornece um cache de validadores de modelo.

Serviços de várias instâncias

Serviço DESCRIÇÃO
IFilterprovider Retorna uma lista de filtros para uma ação do controlador.
ModelBinderProvider Retorna um associador de modelo para um determinado tipo.
ModelMetadataProvider Fornece metadados para um modelo.
ModelValidatorProvider Fornece um validador para um modelo.
ValueProviderFactory Cria um provedor de valor. Para obter mais informações, consulte a postagem no blog de Mike Stall como criar um provedor de valor personalizado no WebAPI

Para adicionar uma implementação personalizada a um serviço de várias instâncias, chame Adicionar ou Inserir na coleção de Serviços :

config.Services.Add(typeof(IFilterProvider), new MyFilterProvider());

Para substituir um serviço de instância única por uma implementação personalizada, chame replace na coleção de Serviços :

config.Services.Replace(typeof(ITraceWriter), new MyTraceWriter());

Configuração por controlador

Você pode substituir as seguintes configurações por controlador:

  • Formatadores de tipo de mídia
  • Regras de associação de parâmetro
  • Serviços

Para fazer isso, defina um atributo personalizado que implemente a interface IControllerConfiguration . Em seguida, aplique o atributo ao controlador.

O exemplo a seguir substitui os formatadores de tipo de mídia padrão por um formatador personalizado.

using System;
using System.Web.Http;
using System.Web.Http.Controllers;

namespace WebApplication1.Controllers
{

    public class UseMyFormatterAttribute : Attribute, IControllerConfiguration
    {
        public void Initialize(HttpControllerSettings settings,
            HttpControllerDescriptor descriptor)
        {
            // Clear the formatters list.
            settings.Formatters.Clear();

            // Add a custom media-type formatter.
            settings.Formatters.Add(new MyFormatter());
        }
    }

    [UseMyFormatter]
    public class ValuesController : ApiController
    {
        // Controller methods not shown...
    }
}

O método IControllerConfiguration. Initialize usa dois parâmetros:

  • Um objeto HttpControllerSettings
  • Um objeto HttpControllerDescriptor

O HttpControllerDescriptor contém uma descrição do controlador, que você pode examinar para fins informativos (digamos, para distinguir entre dois controladores).

Use o objeto HttpControllerSettings para configurar o controlador. Esse objeto contém o subconjunto de parâmetros de configuração que você pode substituir por controlador. As configurações que você não alterar padrão para o objeto HttpConfiguration global.