Konfigurieren von ASP.NET-Web-API 2

Artikel
07/13/2023

In diesem Thema wird beschrieben, wie Sie ASP.NET-Web-API konfigurieren.

Konfigurationseinstellungen
Konfigurieren der Web-API mit ASP.NET Hosting
Konfigurieren der Web-API mit OWIN Self-Hosting
Globale Web-API-Dienste
Konfiguration pro Controller

Konfigurationseinstellungen

Web-API-Konfigurationseinstellungen werden in der HttpConfiguration-Klasse definiert.

Member	BESCHREIBUNG
DependencyResolver	Aktiviert die Abhängigkeitsinjektion für Controller. Weitere Informationen finden Sie unter Verwenden des Web-API-Abhängigkeitslösers.
Filter	Aktionsfilter.
Formatierer	Medienformatierer.
IncludeErrorDetailPolicy	Gibt an, ob der Server Fehlerdetails, z. B. Ausnahmemeldungen und Stapelüberwachungen, in HTTP-Antwortnachrichten enthalten soll. Weitere Informationen finden Sie unter IncludeErrorDetailPolicy.
Initialisierung	Eine Funktion, die die endgültige Initialisierung der HttpConfiguration ausführt.
MessageHandlers	HTTP-Nachrichtenhandler.
ParameterBindingRules	Eine Auflistung von Regeln zum Binden von Parametern für Controlleraktionen.
Eigenschaften	Ein generischer Eigenschaftenbehälter.
Routes	Die Sammlung von Routen. Weitere Informationen finden Sie unter Routing in ASP.NET-Web-API.
Dienste	Die Sammlung von Diensten. Weitere Informationen finden Sie unter Dienste.

Voraussetzungen

Visual Studio 2017 – Community, Professional oder Enterprise Edition.

Konfigurieren der Web-API mit ASP.NET Hosting

Konfigurieren Sie in einer ASP.NET-Anwendung die Web-API, indem Sie GlobalConfiguration.Configure in der Application_Start-Methode aufrufen. Die Configure-Methode akzeptiert einen Delegaten mit einem einzelnen Parameter vom Typ HttpConfiguration. Führen Sie ihre gesamte Konfiguration innerhalb des Delegaten aus.

Hier sehen Sie ein Beispiel für die Verwendung eines anonymen Delegaten:

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 richtet die Projektvorlage "ASP.NET Webanwendung" automatisch den Konfigurationscode ein, wenn Sie im Dialogfeld Neues ASP.NET Projekt die Option "Web-API" auswählen.

Die Projektvorlage erstellt eine Datei namens WebApiConfig.cs im Ordner App_Start. Diese Codedatei definiert den Delegaten, in den Sie Ihren Web-API-Konfigurationscode einfügen sollen.

Screenshot des Dialogfelds

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

Die Projektvorlage fügt auch den Code hinzu, der den Delegaten aus Application_Start aufruft.

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

Konfigurieren der Web-API mit OWIN-Self-Hosting

Wenn Sie sich selbst mit OWIN hosten, erstellen Sie eine neue HttpConfiguration-instance. Führen Sie eine beliebige Konfiguration für diese instance aus, und übergeben Sie dann die instance an die Owin.UseWebApi-Erweiterungsmethode.

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

Das Tutorial Verwenden von OWIN für Self-Host ASP.NET-Web-API 2 zeigt die vollständigen Schritte.

Globale Web-API-Dienste

Die HttpConfiguration.Services-Auflistung enthält eine Reihe von globalen Diensten, die von der Web-API zum Ausführen verschiedener Aufgaben verwendet werden, z. B. Controllerauswahl und Inhaltsverhandlung.

Hinweis

Die Services-Auflistung ist kein allgemeiner Mechanismus für die Dienstermittlung oder Abhängigkeitsinjektion. Es werden nur Diensttypen gespeichert, die dem Web-API-Framework bekannt sind.

Die Services-Auflistung wird mit einem Standardsatz von Diensten initialisiert, und Sie können Ihre eigenen benutzerdefinierten Implementierungen bereitstellen. Einige Dienste unterstützen mehrere Instanzen, während andere nur eine instance haben können. (Sie können jedoch auch Dienste auf Controllerebene bereitstellen. Weitere Informationen finden Sie unter Konfiguration pro Controller.

Single-Instance Services

Dienst	BESCHREIBUNG
IActionValueBinder	Ruft eine Bindung für einen Parameter ab.
IApiExplorer	Ruft Beschreibungen der APIs ab, die von der Anwendung verfügbar gemacht werden. Weitere Informationen finden Sie unter Erstellen einer Hilfeseite für eine Web-API.
IAssembliesResolver	Ruft eine Liste der Assemblys für die Anwendung ab. Weitere Informationen finden Sie unter Routing und Aktionsauswahl.
IBodyModelValidator	Überprüft ein Modell, das von einem Medientypformatierer aus dem Anforderungstext gelesen wird.
IContentNegotiator	Führt Inhaltsaushandlung aus.
IDocumentationProvider	Stellt Dokumentation für APIs bereit. Der Standardwert ist NULL. Weitere Informationen finden Sie unter Erstellen einer Hilfeseite für eine Web-API.
IHostBufferPolicySelector	Gibt an, ob der Host HTTP-Nachrichtenentitätstexte puffern soll.
IHttpActionInvoker	Ruft eine Controlleraktion auf. Weitere Informationen finden Sie unter Routing und Aktionsauswahl.
IHttpActionSelector	Wählt eine Controlleraktion aus. Weitere Informationen finden Sie unter Routing und Aktionsauswahl.
IHttpControllerActivator	Aktiviert einen Controller. Weitere Informationen finden Sie unter Routing und Aktionsauswahl.
IHttpControllerSelector	Wählt einen Controller aus. Weitere Informationen finden Sie unter Routing und Aktionsauswahl.
IHttpControllerTypeResolver	Stellt eine Liste der Web-API-Controllertypen in der Anwendung bereit. Weitere Informationen finden Sie unter Routing und Aktionsauswahl.
ITraceManager	Initialisiert das Ablaufverfolgungsframework. Weitere Informationen finden Sie unter Ablaufverfolgung in ASP.NET-Web-API.
ITraceWriter	Stellt einen Ablaufverfolgungsschreiber bereit. Der Standardwert ist ein "No-Op"-Ablaufverfolgungsschreiber. Weitere Informationen finden Sie unter Ablaufverfolgung in ASP.NET-Web-API.
IModelValidatorCache	Stellt einen Cache mit Modellüberprüfungen bereit.

Multiple-Instance Services

Dienst	BESCHREIBUNG
IFilterProvider	Gibt eine Liste von Filtern für eine Controlleraktion zurück.
ModelBinderProvider	Gibt einen Modellbinder für einen bestimmten Typ zurück.
ModelMetadataProvider	Stellt Metadaten für ein Modell bereit.
ModelValidatorProvider	Stellt einen Validierungsator für ein Modell bereit.
ValueProviderFactory	Erstellt einen Wertanbieter. Weitere Informationen finden Sie im Blogbeitrag Erstellen eines benutzerdefinierten Wertanbieters in WebAPI von Mike Stall.

Um einem Dienst mit mehreren instance eine benutzerdefinierte Implementierung hinzuzufügen, rufen Sie add or Insert on the Services collection auf:

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

Um einen Single-instance-Dienst durch eine benutzerdefinierte Implementierung zu ersetzen, rufen Sie Ersetzen für die Services-Auflistung auf:

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

Per-Controller-Konfiguration

Sie können die folgenden Einstellungen auf Controllerbasis überschreiben:

Medientypformatierer
Parameterbindungsregeln
Dienste

Definieren Sie hierzu ein benutzerdefiniertes Attribut, das die IControllerConfiguration-Schnittstelle implementiert. Wenden Sie dann das Attribut auf den Controller an.

Im folgenden Beispiel werden die Standardformatierer für Medientypen durch einen benutzerdefinierten Formatierer ersetzt.

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

Die IControllerConfiguration.Initialize-Methode benötigt zwei Parameter:

Ein HttpControllerSettings-Objekt
Ein HttpControllerDescriptor-Objekt

Der HttpControllerDescriptor enthält eine Beschreibung des Controllers, die Sie zu Informationszwecken untersuchen können (z. B. zur Unterscheidung zwischen zwei Controllern).

Verwenden Sie das HttpControllerSettings-Objekt , um den Controller zu konfigurieren. Dieses Objekt enthält die Teilmenge von Konfigurationsparametern, die Sie pro Controller überschreiben können. Alle Einstellungen, die Sie nicht standardmäßig auf das globale HttpConfiguration-Objekt ändern.