Partager via


Configuration de API Web ASP.NET 2

Cette rubrique explique comment configurer API Web ASP.NET.

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 .

Capture d’écran de la boîte de dialogue Nouveau projet point NET avec la case Web A P I sélectionnée pour configurer automatiquement le code de configuration.

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.

Capture d’écran de Explorateur de solutions boîte de dialogue, avec web A P I Config point c s en rouge, à l’intérieur du dossier De démarrage de l’application.

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.