Configurando ASP.NET Web API 2

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

• Definições de configuração
• Configurando a API Web com hospedagem ASP.NET
• Configurando a API Web com auto-hospedagem OWIN
• Serviços globais de API Web
• Configuração por controlador

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 de 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.

Pré-requisitos

Visual Studio 2017 Community, Professional ou Enterprise Edition.

Configurando a API Web com hospedagem ASP.NET

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

Aqui está um exemplo usando 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 da pasta App_Start. 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 de Application_Start.

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

Configurando a API Web com o OWIN Self-Hosting

Se você estiver se auto-hospedando com o OWIN, crie uma nova instância httpConfiguration . Execute qualquer configuração nessa instância e 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 o OWIN para Self-Host ASP.NET Web API 2 mostra as etapas completas.

Serviços globais de API Web

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

Observação

A coleção Services não é um mecanismo de uso 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 Services é 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 do Single-Instance

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 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 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 Web.
IHostBufferPolicySelector	Indica se o host deve armazenar em buffer 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 de 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 "sem operação". Consulte Rastreamento em ASP.NET Web API.
IModelValidatorCache	Fornece um cache de validadores de modelo.

serviços Multiple-Instance

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 Services :

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 Services :

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

Configuração do Per-Controller

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 implementa 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 (por exemplo, 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. Todas as configurações que você não alterar padrão para o objeto HttpConfiguration global.