Routing in der ASP.NET Web-API

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

Hinweis

Wenn Sie mit ASP.NET MVC vertraut sind, ähnelt das Web-API-Routing dem MVC-Routing sehr. Der Standard Unterschied besteht darin, dass die Web-API das HTTP-Verb und nicht den URI-Pfad verwendet, um die Aktion auszuwählen. Sie können auch Routing im MVC-Stil in der Web-API verwenden. In diesem Artikel wird keine Kenntnis ASP.NET MVC vorausgesetzt.

Routingtabellen

In ASP.NET-Web-API ist ein Controller eine Klasse, die HTTP-Anforderungen verarbeitet. Die öffentlichen Methoden des Controllers werden als Aktionsmethoden oder einfach 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 -Klasse finden Sie unter Konfigurieren ASP.NET-Web-APIWebApiConfig.

Wenn Sie die Web-API selbst hosten, müssen Sie die Routingtabelle direkt für das HttpSelfHostConfiguration Objekt festlegen. Weitere Informationen finden Sie unter Selbsthosten 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 den Fehler 404. Die folgenden URIs entsprechen beispielsweise der Standardroute:

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

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

• /contacts/1

Hinweis

Der Grund für die Verwendung von "api" in der Route besteht darin, Kollisionen mit ASP.NET MVC-Routing zu vermeiden. Auf diese Weise können Sie "/Contacts" zu einem MVC-Controller und "/api/contacts" zu einem Web-API-Controller wechseln. Wenn Ihnen diese Konvention nicht gefällt, können Sie natürlich die Standardroutentabelle ändern.

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 dann nach einer Aktion, deren Name mit diesem HTTP-Verbnamen beginnt. Bei 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 DIE Verben GET, POST, PUT, DELETE, HEAD, OPTIONS und PATCH. Sie können andere HTTP-Verben aktivieren, indem Sie Attribute auf Ihrem Controller verwenden. Ein Beispiel dafür sehen Wir später.
• Andere Platzhaltervariablen in der Routenvorlage, z. B . {id}, werden Aktionsparametern zugeordnet.

Schauen wir uns ein Beispiel an. Angenommen, Sie definieren den folgenden Controller:

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

Hier sind einige mögliche HTTP-Anforderungen sowie die Aktion aufgeführt, die für jede aufgerufen wird:

HTTP-Verb	URI-Pfad	Action	Parameter
GET	api/products	GetAllProducts	(none)
GET	api/products/4	GetProductById	4
Delete	api/products/4	DeleteProduct	4
POST	api/products	(keine Übereinstimmung)

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 explizit für eine Aktion 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 andere HTTP-Verben als 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

Bei der Standardroutingvorlage verwendet die Web-API das HTTP-Verb, um die Aktion auszuwählen. Sie können jedoch auch eine Route erstellen, bei 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 dieser Art des Routings 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 API im RPC-Stil 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 POST:

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

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

Nicht-Aktionen

Verwenden Sie das [NonAction] -Attribut, um zu verhindern, dass eine Methode als Aktion aufgerufen wird. Dadurch wird dem Framework signalisiert, dass es sich bei der Methode nicht um eine Aktion handelt, auch wenn sie andernfalls mit den Routingregeln übereinstimmt.

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

Weitere Informationen

In diesem Thema wurde eine allgemeine Ansicht des Routings bereitgestellt. Weitere Informationen finden Sie unter Routing- und Aktionsauswahl, in der genau beschrieben wird, wie das Framework einen URI mit einer Route vergleicht, einen Controller auswählt und dann die aktion auswählt, die aufgerufen werden soll.