Routing in ASP.NET Web-API

In diesem Artikel wird beschrieben, wie ASP.NET Web-API HTTP-Anforderungen an Controller weiter leitet.

Routingtabellen

In ASP.NET Web-API ist ein Controller eine Klasse, die HTTP-Anforderungen verarbeitet. Die öffentlichen Methoden des Controllers werden als Aktionsmethoden oder einfache Aktionen bezeichnet. Wenn das Web-API-Framework eine Anforderung empfängt, leitet es die Anforderung an eine Aktion weiter.

Um zu bestimmen, welche Aktion aufgerufen werden soll, verwendet das Framework eine Routingtabelle. Die Visual Studio-Projektvorlage für die Web-API erstellt eine Standardroute:

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Diese Route wird in der datei WebApiConfig.cs definiert, die im verzeichnis App_Start abgelegt wird:

Weitere Informationen zur WebApiConfig Klasse finden Sie unter Konfigurieren ASP.NET Web-API.

Wenn Sie die Web-API selbst hosten, müssen Sie die Routingtabelle direkt für das HttpSelfHostConfiguration Objekt festlegen. Weitere Informationen finden Sie unterSelf-Host einer Web-API.

Jeder Eintrag in der Routingtabelle enthält eine Routenvorlage. Die Standardroutenvorlage für die Web-API lautet "api/{controller}/{id}". In dieser Vorlage ist "api" ein Literalpfadsegment, und {controller} und {id} sind Platzhaltervariablen.

Wenn das Web-API-Framework eine HTTP-Anforderung empfängt, versucht es, den URI mit einer der Routenvorlagen in der Routingtabelle abzugleichen. Wenn keine Route übereinstimmt, erhält der Client einen Fehler von 404. Die folgenden URIs entsprechen beispielsweise der Standardroute:

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

Der folgende URI stimmt jedoch nicht überein, da das Segment "api" fehlt:

• /contacts/1

Sobald eine übereinstimmende Route gefunden wurde, wählt Die Web-API den Controller und die Aktion aus:

• Um den Controller zu finden, fügt die Web-API dem Wert der {controller} -Variablen "Controller" hinzu.
• Um die Aktion zu finden, sucht die Web-API das HTTP-Verb und sucht dann nach einer Aktion, deren Name mit diesem HTTP-Verbnamen beginnt. Mit einer GET-Anforderung sucht die Web-API beispielsweise nach einer Aktion mit dem Präfix "Get", z. B. "GetContact" oder "GetAllContacts". Diese Konvention gilt nur für GET-, POST-, PUT-, DELETE-, HEAD-, OPTIONS- und PATCH-Verben. Sie können andere HTTP-Verben mithilfe von Attributen auf dem Controller aktivieren. Wir werden später ein Beispiel dafür sehen.
• Andere Platzhaltervariablen in der Routenvorlage, z. B. {id}, werden Aktionsparametern zugeordnet.

Betrachten wir dazu ein Beispiel. Angenommen, Sie definieren den folgenden Controller:

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

Nachfolgend sind einige mögliche HTTP-Anforderungen zusammen mit der Aktion aufgeführt, die für jede aufgerufen wird:

Beachten Sie, dass das {id} -Segment des URI(sofern vorhanden) dem ID-Parameter der Aktion zugeordnet ist. In diesem Beispiel definiert der Controller zwei GET-Methoden, eine mit einem ID-Parameter und eine ohne Parameter.

Beachten Sie außerdem, dass die POST-Anforderung fehlschlägt, da der Controller keine "Post..."-Methode definiert.

Routingvariationen

Im vorherigen Abschnitt wurde der grundlegende Routingmechanismus für ASP.NET Web-API beschrieben. In diesem Abschnitt werden einige Variationen beschrieben.

HTTP-Verben

Anstatt die Benennungskonvention für HTTP-Verben zu verwenden, können Sie das HTTP-Verb für eine Aktion explizit angeben, indem Sie die Aktionsmethode mit einem der folgenden Attribute versehen:

• [HttpGet]
• [HttpPut]
• [HttpPost]
• [HttpDelete]
• [HttpHead]
• [HttpOptions]
• [HttpPatch]

Im folgenden Beispiel wird die FindProduct Methode GET-Anforderungen zugeordnet:

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

Um mehrere HTTP-Verben für eine Aktion zuzulassen oder HTTP-Verben außer GET, PUT, POST, DELETE, HEAD, OPTIONS und PATCH zuzulassen, verwenden Sie das [AcceptVerbs] Attribut, das eine Liste von HTTP-Verben akzeptiert.

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

Routing nach Aktionsname

Mit der Standardroutingvorlage verwendet die Web-API das HTTP-Verb, um die Aktion auszuwählen. Sie können jedoch auch eine Route erstellen, in der der Aktionsname im URI enthalten ist:

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

In dieser Routenvorlage benennt der {action} -Parameter die Aktionsmethode auf dem Controller. Verwenden Sie bei diesem Routingstil Attribute, um die zulässigen HTTP-Verben anzugeben. Angenommen, Ihr Controller verfügt über die folgende Methode:

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

In diesem Fall würde eine GET-Anforderung für "api/products/details/1" der Details Methode zugeordnet. Diese Art des Routings ähnelt ASP.NET MVC und kann für eine RPC-Stil-API geeignet sein.

Sie können den Aktionsnamen überschreiben, indem Sie das [ActionName] Attribut verwenden. Im folgenden Beispiel gibt es zwei Aktionen, die "api/products/thumbnail/id" zugeordnet sind. Eine unterstützt GET und die andere unterstützt POST:

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

Nicht-Aktivitäten

Um zu verhindern, dass eine Methode als Aktion aufgerufen wird, verwenden Sie das [NonAction] Attribut. Dies signalisiert dem Framework, dass die Methode keine Aktion ist, auch wenn sie andernfalls den Routingregeln entsprechen würde.

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

Weiterführende Lektüre

In diesem Thema wird eine allgemeine Übersicht zum Routing bereitgestellt. Weitere Details finden Sie unter Routing und Aktionsauswahl, in dem genau beschrieben wird, wie das Framework einem URI einer Route zuordnet, einen Controller auswählt und dann die Aktion zur Ausführung auswählt.