Configurazione di API Web ASP.NET 2

Questo argomento descrive come configurare API Web ASP.NET.

• Impostazioni di configurazione
• Configurazione dell'API Web con l'hosting di ASP.NET
• Configurazione dell'API Web con self-hosting OWIN
• Servizi API Web globali
• Configurazione per controller

Impostazioni di configurazione

Le impostazioni di configurazione dell'API Web sono definite nella classe HttpConfiguration .

Membro	Descrizione
DependencyResolver	Abilita l'inserimento delle dipendenze per i controller. Vedere Uso del sistema di risoluzione delle dipendenze dell'API Web.
Filtri	Filtri azioni.
Formattatori	Formattatori di tipo multimediale.
IncludeErrorDetailPolicy	Specifica se il server deve includere i dettagli degli errori, ad esempio messaggi di eccezione e tracce dello stack, nei messaggi di risposta HTTP. Vedere IncludeErrorDetailPolicy.
Inizializzatore	Funzione che esegue l'inizializzazione finale di HttpConfiguration.
MessageHandlers	Gestori di messaggi HTTP.
ParameterBindingRules	Raccolta di regole per i parametri di associazione sulle azioni del controller.
Proprietà	Borsa di proprietà generica.
Route	Raccolta di route. Vedere Routing in API Web ASP.NET.
Services	Raccolta di servizi. Vedere Servizi.

Prerequisiti

Visual Studio 2017 Community, Professional o Enterprise edition.

Configurazione dell'API Web con l'hosting di ASP.NET

In un'applicazione ASP.NET configurare l'API Web chiamando GlobalConfiguration.Configure nel metodo Application_Start . Il metodo Configure accetta un delegato con un singolo parametro di tipo HttpConfiguration. Eseguire tutte le configurazioni all'interno del delegato.

Ecco un esempio che usa un delegato anonimo:

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

In Visual Studio 2017 il modello di progetto "applicazione Web ASP.NET" configura automaticamente il codice di configurazione, se si seleziona "API Web" nella finestra di dialogo Nuovo ASP.NET Progetto .

Il modello di progetto crea un file denominato WebApiConfig.cs all'interno della cartella App_Start. Questo file di codice definisce il delegato in cui è necessario inserire il codice di configurazione dell'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 }
            );
        }
    }
}

Il modello di progetto aggiunge anche il codice che chiama il delegato da Application_Start.

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

Configurazione dell'API Web con OWIN Self-Hosting

Se si esegue l'self-hosting con OWIN, creare una nuova istanza di HttpConfiguration . Eseguire qualsiasi configurazione in questa istanza e quindi passare l'istanza al metodo di estensione 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); 
    } 
}

L'esercitazione Usa OWIN per Self-Host API Web ASP.NET 2 mostra i passaggi completi.

Servizi API Web globali

L'insieme HttpConfiguration.Services contiene un set di servizi globali usati dall'API Web per eseguire varie attività, ad esempio la selezione del controller e la negoziazione del contenuto.

Nota

L'insieme Services non è un meccanismo per utilizzo generico per l'individuazione del servizio o l'inserimento delle dipendenze. Archivia solo i tipi di servizio noti al framework API Web.

L'insieme Services viene inizializzato con un set predefinito di servizi e è possibile fornire implementazioni personalizzate. Alcuni servizi supportano più istanze, mentre altri possono avere solo un'istanza. Tuttavia, è anche possibile fornire servizi a livello di controller. Vedere Configurazione per controller.

Single-Instance Servizi

Servizio	Descrizione
IActionValueBinder	Ottiene un'associazione per un parametro.
IApiExplorer	Ottiene le descrizioni delle API esposte dall'applicazione. Vedere Creazione di una pagina della Guida per un'API Web.
IAssembliesResolver	Ottiene un elenco degli assembly per l'applicazione. Vedere Routing e selezione delle azioni.
IBodyModelValidator	Convalida un modello letto dal corpo della richiesta da un formattatore di tipo multimediale.
IContentNegotiator	Esegue la negoziazione del contenuto.
IDocumentationProvider	Fornisce la documentazione per le API. Il valore predefinito è Null. Vedere Creazione di una pagina della Guida per un'API Web.
IHostBufferPolicySelector	Indica se l'host deve bufferare i corpi dell'entità del messaggio HTTP.
IHttpActionInvoker	Richiama un'azione controller. Vedere Routing e selezione delle azioni.
IHttpActionSelector	Seleziona un'azione controller. Vedere Routing e selezione delle azioni.
IHttpControllerActivator	Attiva un controller. Vedere Routing e selezione delle azioni.
IHttpControllerSelector	Seleziona un controller. Vedere Routing e selezione delle azioni.
IHttpControllerTypeResolver	Fornisce un elenco dei tipi di controller API Web nell'applicazione. Vedere Routing e selezione delle azioni.
ITraceManager	Inizializza il framework di traccia. Vedere Traccia in API Web ASP.NET.
Itracewriter	Fornisce un writer di traccia. Il valore predefinito è un writer di traccia "no-op". Vedere Traccia in API Web ASP.NET.
IModelValidatorCache	Fornisce una cache di validator di modelli.

Multiple-Instance Servizi

Servizio	Descrizione
Ifilterprovider	Restituisce un elenco di filtri per un'azione controller.
ModelBinderProvider	Restituisce un bindinger modello per un determinato tipo.
Modelmetadataprovider	Fornisce metadati per un modello.
ModelValidatorProvider	Fornisce un validator per un modello.
ValueProviderFactory	Crea un provider di valori. Per altre informazioni, vedere Il post di blog di Mike Stall Come creare un provider di valori personalizzato in WebAPI

Per aggiungere un'implementazione personalizzata a un servizio multiistanza, chiamare Aggiungi o Inserisci nella raccolta Services :

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

Per sostituire un servizio a istanza singola con un'implementazione personalizzata, chiamare Replace nella raccolta Services :

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

configurazione Per-Controller

È possibile eseguire l'override delle impostazioni seguenti in base al controller:

• Formattatori di tipo multimediale
• Regole di associazione dei parametri
• Servizi

A tale scopo, definire un attributo personalizzato che implementa l'interfaccia IControllerConfiguration . Applicare quindi l'attributo al controller.

L'esempio seguente sostituisce i formattatori di tipo multimediale predefiniti con un formattatore personalizzato.

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

Il metodo IControllerConfiguration.Initialize accetta due parametri:

• Oggetto HttpControllerSettings
• Oggetto HttpControllerDescriptor

HttpControllerDescriptor contiene una descrizione del controller, che è possibile esaminare per scopi informativi( ad esempio, per distinguere tra due controller).

Usare l'oggetto HttpControllerSettings per configurare il controller. Questo oggetto contiene il subset di parametri di configurazione che è possibile eseguire l'override su base per controller. Tutte le impostazioni che non si modificano per impostazione predefinita nell'oggetto HttpConfiguration globale.