Partilhar via

Configurando ASP.NET Web API 2

  • Artigo

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

Captura de tela da caixa de diálogo Novo Projeto SP dot NET, com a caixa de seleção Web A P I marcada para configurar automaticamente o código de configuração.

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.

Captura de tela da caixa de diálogo Gerenciador de Soluções, com Web A P I Config dot c s descritos em vermelho, dentro da pasta Iniciar Aplicativo.

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.