Configuration de API Web ASP.NET 2

Cette rubrique explique comment configurer API Web ASP.NET.

• Paramètres de configuration
• Configuration de l’API web avec l’hébergement ASP.NET
• Configuration de l’API web avec L’auto-hébergement OWIN
• Services d’API web globaux
• Configuration par contrôleur

Paramètres de configuration

Les paramètres de configuration de l’API web sont définis dans la classe HttpConfiguration .

Membre	Description
DependencyResolver	Active l’injection de dépendances pour les contrôleurs. Consultez Utilisation du programme de résolution des dépendances de l’API web.
Filtres	Filtres d'action.
Formateurs	Formateurs de type multimédia.
IncludeErrorDetailPolicy	Spécifie si le serveur doit inclure les détails de l’erreur, tels que les messages d’exception et les traces de pile, dans les messages de réponse HTTP. Consultez IncludeErrorDetailPolicy.
Initialiseur	Fonction qui effectue l’initialisation finale de HttpConfiguration.
Gestionnaires de messages	Gestionnaires de messages HTTP.
ParameterBindingRules	Collection de règles pour la liaison de paramètres sur les actions du contrôleur.
Propriétés	Sac de propriétés génériques.
Itinéraires	Collection d’itinéraires. Consultez Routage dans API Web ASP.NET.
Services	Collection de services. Consultez Services.

Prérequis

Visual Studio 2017 édition Communauté, Professionnel ou Entreprise.

Configuration de l’API web avec l’hébergement ASP.NET

Dans une application ASP.NET, configurez l’API web en appelant GlobalConfiguration.Configure dans la méthode Application_Start . La méthode Configure accepte un délégué avec un paramètre unique de type HttpConfiguration. Effectuez toute votre configuration à l’intérieur du délégué.

Voici un exemple d’utilisation d’un délégué anonyme :

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

Dans Visual Studio 2017, le modèle de projet « application web ASP.NET » configure automatiquement le code de configuration, si vous sélectionnez « API web » dans la boîte de dialogue Nouveau projet ASP.NET .

Le modèle de projet crée un fichier nommé WebApiConfig.cs à l’intérieur du dossier App_Start. Ce fichier de code définit le délégué dans lequel vous devez placer le code de configuration de votre 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 }
            );
        }
    }
}

Le modèle de projet ajoute également le code qui appelle le délégué à partir de Application_Start.

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

Configuration de l’API web avec Self-Hosting OWIN

Si vous vous auto-hébergez avec OWIN, créez une nouvelle instance HttpConfiguration. Effectuez une configuration sur ce instance, puis passez le instance à la méthode d’extension 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); 
    } 
}

Le didacticiel Utiliser OWIN pour Self-Host API Web ASP.NET 2 montre les étapes complètes.

Services d’API web globaux

La collection HttpConfiguration.Services contient un ensemble de services globaux que l’API web utilise pour effectuer diverses tâches, telles que la sélection du contrôleur et la négociation du contenu.

Notes

La collection Services n’est pas un mécanisme à usage général pour la découverte de service ou l’injection de dépendances. Il stocke uniquement les types de services connus de l’infrastructure d’API web.

La collection Services est initialisée avec un ensemble de services par défaut et vous pouvez fournir vos propres implémentations personnalisées. Certains services prennent en charge plusieurs instances, tandis que d’autres ne peuvent avoir qu’une seule instance. (Toutefois, vous pouvez également fournir des services au niveau du contrôleur ; consultez Configuration par contrôleur.

Single-Instance Services

Service	Description
IActionValueBinder	Obtient une liaison pour un paramètre.
IApiExplorer	Obtient des descriptions des API exposées par l’application. Consultez Création d’une page d’aide pour une API web.
IAssembliesResolver	Obtient la liste des assemblys de l’application. Consultez Routage et sélection d’actions.
IBodyModelValidator	Valide un modèle lu à partir du corps de la requête par un formateur de type multimédia.
IContentNegotiator	Exécute la négociation de contenu.
IDocumentationProvider	Fournit une documentation pour les API. La valeur par défaut est null. Consultez Création d’une page d’aide pour une API web.
IHostBufferPolicySelector	Indique si l’hôte doit mettre en mémoire tampon les corps d’entité de message HTTP.
IHttpActionInvoker	Appelle une action de contrôleur. Consultez Routage et sélection d’actions.
IHttpActionSelector	Sélectionne une action de contrôleur. Consultez Routage et sélection d’actions.
IHttpControllerActivator	Active un contrôleur. Consultez Routage et sélection d’actions.
IHttpControllerSelector	Sélectionne un contrôleur. Consultez Routage et sélection d’actions.
IHttpControllerTypeResolver	Fournit la liste des types de contrôleurs d’API web dans l’application. Consultez Routage et sélection d’actions.
ITraceManager	Initialise l’infrastructure de suivi. Consultez Suivi dans API Web ASP.NET.
ITraceWriter	Fournit un enregistreur de traces. La valeur par défaut est un enregistreur de trace « no-op ». Consultez Suivi dans API Web ASP.NET.
IModelValidatorCache	Fournit un cache de validateurs de modèle.

Multiple-Instance Services

Service	Description
IFilterProvider	Retourne une liste de filtres pour une action de contrôleur.
ModelBinderProvider	Retourne un classeur de modèle pour un type donné.
ModelMetadataProvider	Fournit des métadonnées pour un modèle.
ModelValidatorProvider	Fournit un validateur pour un modèle.
ValueProviderFactory	Crée un fournisseur de valeur. Pour plus d’informations, consultez le billet de blog de Mike Stall Comment créer un fournisseur de valeur personnalisé dans WebAPI

Pour ajouter une implémentation personnalisée à un service multi-instance, appelez Ajouter ou Insérer dans la collection Services :

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

Pour remplacer un service à instance unique par une implémentation personnalisée, appelez Replace sur la collection Services :

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

configuration Per-Controller

Vous pouvez remplacer les paramètres suivants par contrôleur :

• Formateurs de type multimédia
• Règles de liaison de paramètre
• Services

Pour ce faire, définissez un attribut personnalisé qui implémente l’interface IControllerConfiguration . Ensuite, appliquez l’attribut au contrôleur.

L’exemple suivant remplace les formateurs de type multimédia par défaut par un formateur personnalisé.

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

La méthode IControllerConfiguration.Initialize prend deux paramètres :

• Objet HttpControllerSettings
• Objet HttpControllerDescriptor

HttpControllerDescriptor contient une description du contrôleur, que vous pouvez examiner à des fins d’information (par exemple, pour faire la distinction entre deux contrôleurs).

Utilisez l’objet HttpControllerSettings pour configurer le contrôleur. Cet objet contient le sous-ensemble de paramètres de configuration que vous pouvez remplacer par contrôleur. Tous les paramètres que vous ne modifiez pas par défaut en l’objet HttpConfiguration global.