Configuración de ASP.NET Web API 2

  • Artículo

En este tema, se describe cómo configurar ASP.NET Web API.

Opciones de configuración

Los valores de configuración de Web API se definen en la clase HttpConfiguration.

Miembro Descripción
DependencyResolver Habilita la inserción de dependencias para los controladores. Consulte Uso del solucionador de dependencias de Web API.
Filters Filtros de acciones.
Formateadores Formateadores de tipo multimedia.
IncludeErrorDetailPolicy Especifica si el servidor debe incluir detalles de error, como mensajes de excepción y seguimientos de pila, en mensajes de respuesta HTTP. Consulte IncludeErrorDetailPolicy.
Inicializador Función que realiza la inicialización final de HttpConfiguration.
MessageHandlers Controladores de mensajes HTTP.
ParameterBindingRules Colección de reglas para enlazar parámetros en las acciones del controlador.
Propiedades Contenedor de propiedades genérico.
Rutas Colección de rutas. Consulte Enrutamiento en ASP.NET Web API.
Servicios La colección de servicios. Consulte Servicios.

Requisitos previos

Visual Studio 2017 Community, Professional o Enterprise.

Configuración de Web API con hospedaje de ASP.NET

En una aplicación ASP.NET, configure Web API llamando a GlobalConfiguration.Configure en el método Application_Start. El método Configure toma un delegado con un único parámetro de tipo HttpConfiguration. Realice toda la configuración dentro del delegado.

Este es un ejemplo mediante un 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 }
                );
            });
        }
    }
}

En Visual Studio 2017, la plantilla de proyecto "ASP.NET Web Application" configura automáticamente el código de configuración si selecciona "Web API" en el cuadro de diálogo Nuevo proyecto de ASP.NET.

Screenshot of New A S P dot NET Project dialog, with Web A P I checkbox selected to automatically set up configuration code.

La plantilla de proyecto crea un archivo denominado WebApiConfig.cs dentro de la carpeta App_Start. Este archivo de código define el delegado donde debe colocar el código de configuración de Web API.

Screenshot of Solution Explorer dialog, with Web A P I Config dot c s outlined in red, inside App Start folder.

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

La plantilla de proyecto también agrega el código que llama al delegado desde Application_Start.

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

Configuración de Web API con autohospedaje de OWIN

Si está usando el autohospedaje con OWIN, cree una nueva instancia de HttpConfiguration. Realice cualquier configuración en esta instancia y, a continuación, pase la instancia al método de extensión 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); 
    } 
}

En el tutorial Uso de OWIN para autohospedar ASP.NET Web API 2, se muestran los pasos completos.

Servicios de Web API globales

La colección HttpConfiguration.Services contiene un conjunto de servicios globales que Web API usa para realizar diversas tareas, como la selección del controlador y la negociación de contenido.

Nota:

La colección Services no es un mecanismo de uso general para la detección de servicios o la inserción de dependencias. Solo almacena los tipos de servicio que se conocen en el marco de Web API.

La colección Services se inicializa con un conjunto predeterminado de servicios y puede proporcionar sus propias implementaciones personalizadas. Algunos servicios admiten varias instancias, mientras que otras solo pueden tener una instancia. (Sin embargo, también puede proporcionar servicios en el nivel de controlador; consulte Configuración por controlador.

Servicios de instancia única

Servicio Descripción
IActionValueBinder Obtiene un enlace para un parámetro.
IApiExplorer Obtiene descripciones de las API expuestas por la aplicación. Consulte Creación de una página de ayuda para una instancia de Web API.
IAssembliesResolver Obtiene una lista de los ensamblados de la aplicación. Consulte Selección de enrutamiento y acción.
IBodyModelValidator Valida un modelo que se lee desde el cuerpo de la solicitud mediante un formateador de tipo multimedia.
IContentNegotiator Realiza la negociación de contenido.
IDocumentationProvider Proporciona documentación para las API. El valor predeterminado es null. Consulte Creación de una página de ayuda para una instancia de Web API.
IHostBufferPolicySelector Indica si el host debe almacenar en búfer los cuerpos de entidad del mensaje HTTP.
IHttpActionInvoker Invoca una acción de controlador. Consulte Selección de enrutamiento y acción.
IHttpActionSelector Selecciona una acción de controlador. Consulte Selección de enrutamiento y acción.
IHttpControllerActivator Activa un control. Consulte Selección de enrutamiento y acción.
IHttpControllerSelector Selecciona un controlador. Consulte Selección de enrutamiento y acción.
IHttpControllerTypeResolver Proporciona una lista de los tipos de controlador de Web API de la aplicación. Consulte Selección de enrutamiento y acción.
ITraceManager Inicializa el marco de seguimiento. Consulte Seguimiento en ASP.NET Web API.
ITraceWriter Proporciona un escritor de seguimiento. El valor predeterminado es un escritor de seguimiento "sin operación". Consulte Seguimiento en ASP.NET Web API.
IModelValidatorCache Proporciona una memoria caché de validadores de modelos.

Servicios de varias instancias

Servicio Descripción
IFilterProvider Devuelve una lista de filtros para una acción de controlador.
ModelBinderProvider Devuelve un enlazador de modelos para un tipo determinado.
ModelMetadataProvider Proporciona metadatos para un modelo.
ModelValidatorProvider Proporciona un validador para un modelo.
ValueProviderFactory Crea un proveedor de valores. Para más información, consulte la entrada de blog Cómo crear un proveedor de valores personalizados en WebAPI de Mike Stall

Para agregar una implementación personalizada a un servicio de varias instancias, llame a Add o Insert en la colección Services:

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

Para reemplazar un servicio de instancia única por una implementación personalizada, llame a Replace en la colección Services:

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

Configuración por controlador

Puede invalidar la siguiente configuración individual por controlador:

  • Formateadores de tipo multimedia
  • Reglas de enlace de parámetros
  • Servicios

Para ello, defina un atributo personalizado que implemente la interfaz IControllerConfiguration. Después, aplique el atributo al controlador.

En el ejemplo siguiente, se reemplazan los formateadores de tipo multimedia predeterminados por un formateador 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...
    }
}

El método IControllerConfiguration.Initialize toma dos parámetros:

  • Un objeto HttpControllerSettings
  • Un objeto HttpControllerDescriptor

El HttpControllerDescriptor contiene una descripción del controlador, que puede examinar con fines informativos (por ejemplo, distinguir entre dos controladores).

Use el objeto HttpControllerSettings para configurar el controlador. Este objeto contiene el subconjunto de parámetros de configuración que se pueden invalidar por cada controlador individual. Cualquier configuración que no cambie se asigna de forma predeterminada al objeto global HttpConfiguration.