Freigeben über


Konfigurieren von ASP.NET-Web-API 2

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

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.

Screenshot des Dialogfelds

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.