ASP.NET Web API 'de yönlendirmeRouting in ASP.NET Web API

, Mike te sonby Mike Wasson

Bu makalede, ASP.NET Web API 'SI, HTTP isteklerini denetleyicilere nasıl yönlendirdiğini açıklar.This article describes how ASP.NET Web API routes HTTP requests to controllers.

Note

ASP.NET MVC hakkında bilgi sahibiyseniz, Web API yönlendirmesi MVC yönlendirmeye çok benzer.If you are familiar with ASP.NET MVC, Web API routing is very similar to MVC routing. Temel fark, Web API 'sinin eylemi seçmek için URI yolunu değil HTTP fiilini kullanması gerektiğidir.The main difference is that Web API uses the HTTP verb, not the URI path, to select the action. Ayrıca, Web API 'sinde MVC stili yönlendirmeyi de kullanabilirsiniz.You can also use MVC-style routing in Web API. Bu makalede, ASP.NET MVC hakkında herhangi bir bilgi varsayılmaktadır.This article does not assume any knowledge of ASP.NET MVC.

Yönlendirme tablolarıRouting Tables

ASP.NET Web API 'sinde, DENETLEYICI http isteklerini işleyen bir sınıftır.In ASP.NET Web API, a controller is a class that handles HTTP requests. Denetleyicinin genel yöntemlerine eylem yöntemleri veya yalnızca Eylemlerdenir.The public methods of the controller are called action methods or simply actions. Web API çerçevesi bir istek aldığında, isteği bir eyleme yönlendirir.When the Web API framework receives a request, it routes the request to an action.

Hangi eylemin çalıştırılacağını öğrenmek için Framework bir yönlendirme tablosukullanır.To determine which action to invoke, the framework uses a routing table. Web API 'SI için Visual Studio proje şablonu varsayılan bir yol oluşturur:The Visual Studio project template for Web API creates a default route:

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

Bu yol, uygulama _ Başlangıç dizinine yerleştirilmiş WebApiConfig.cs dosyasında tanımlanmıştır:This route is defined in the WebApiConfig.cs file, which is placed in the App_Start directory:

Sınıfı hakkında daha fazla bilgi için WebApiConfig bkz. ASP.NET Web API 'sini yapılandırma.For more information about the WebApiConfig class, see Configuring ASP.NET Web API.

Web API 'sini Self barındırdıysanız, yönlendirme tablosunu doğrudan nesne üzerinde ayarlamanız gerekir HttpSelfHostConfiguration .If you self-host Web API, you must set the routing table directly on the HttpSelfHostConfiguration object. Daha fazla bilgi için bkz. kendi kendine konak bir Web API 'si.For more information, see Self-Host a Web API.

Yönlendirme tablosundaki her giriş bir yol şablonuiçerir.Each entry in the routing table contains a route template. Web API 'si için varsayılan yol şablonu, " API/{Controller}/{id} " .The default route template for Web API is "api/{controller}/{id}". Bu şablonda, " API " bir sabit yol segmenti ve {Controller} ve {id} yer tutucu değişkenleridir.In this template, "api" is a literal path segment, and {controller} and {id} are placeholder variables.

Web API çerçevesi bir HTTP isteği aldığında, URI 'yi yönlendirme tablosundaki yol şablonlarından biriyle eşleştirmeye çalışır.When the Web API framework receives an HTTP request, it tries to match the URI against one of the route templates in the routing table. Hiçbir yol eşleşirse, istemci bir 404 hatası alır.If no route matches, the client receives a 404 error. Örneğin, aşağıdaki URI 'Ler varsayılan yol ile eşleşir:For example, the following URIs match the default route:

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

Ancak, " API segmentine sahip olmadığı için AŞAĞıDAKI URI eşleşmez " :However, the following URI does not match, because it lacks the "api" segment:

  • /Contacts/1/contacts/1

Note

Yol içinde "API" kullanmanın nedeni ASP.NET MVC yönlendirme ile çarpışmalardan kaçınmaktır.The reason for using "api" in the route is to avoid collisions with ASP.NET MVC routing. Bu şekilde, " /Contacts " bir MVC denetleyicisine gidebilir ve " /api/Contacts " bir Web API denetleyicisine gider.That way, you can have "/contacts" go to an MVC controller, and "/api/contacts" go to a Web API controller. Kuşkusuz, bu kuralı beğenmezseniz varsayılan yol tablosunu değiştirebilirsiniz.Of course, if you don't like this convention, you can change the default route table.

Eşleşen bir yol bulunduğunda Web API 'SI denetleyiciyi ve eylemi seçer:Once a matching route is found, Web API selects the controller and the action:

  • Denetleyiciyi bulmak için Web API 'SI, " denetleyiciyi " {Controller} değişkeninin değerine ekler.To find the controller, Web API adds "Controller" to the value of the {controller} variable.
  • Eylemi bulmak için Web API 'SI HTTP fiiline bakar ve sonra adı bu HTTP fiili adıyla başlayan bir eylem arar.To find the action, Web API looks at the HTTP verb, and then looks for an action whose name begins with that HTTP verb name. Örneğin, GET isteği ile Web API 'SI " " , " GetContact " veya " getallcontacts gibi get ile önekli bir eyleme bakar " .For example, with a GET request, Web API looks for an action prefixed with "Get", such as "GetContact" or "GetAllContacts". Bu kural yalnızca GET, POST, PUT, DELETE, HEAD, OPTIONS ve PATCH fiilleri için geçerlidir.This convention applies only to GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH verbs. Denetleyicinizdeki öznitelikleri kullanarak diğer HTTP fiillerini etkinleştirebilirsiniz.You can enable other HTTP verbs by using attributes on your controller. Daha sonra bir örnek görürsünüz.We'll see an example of that later.
  • Yol şablonundaki {ID} gibi diğer yer tutucu değişkenleri eylem parametreleriyle eşleştirilir.Other placeholder variables in the route template, such as {id}, are mapped to action parameters.

Bir örneğe göz atalım.Let's look at an example. Aşağıdaki denetleyiciyi tanımladığınızı varsayalım:Suppose that you define the following controller:

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

İşte, her biri için çağrılan eylem ile birlikte bazı olası HTTP istekleri şunlardır:Here are some possible HTTP requests, along with the action that gets invoked for each:

HTTP fiiliHTTP Verb URI yoluURI Path EylemAction ParametreParameter
GETGET API/ürünlerapi/products GetAllProductsGetAllProducts seçim(none)
GETGET API/ürünler/4api/products/4 GetProductByIdGetProductById 44
DELETEDELETE API/ürünler/4api/products/4 DeleteProductDeleteProduct 44
POSTPOST API/ürünlerapi/products (eşleşme yok)(no match)

Varsa URI 'nin {id} segmentinin, eylemin kimlik parametresine eşlendiğine dikkat edin.Notice that the {id} segment of the URI, if present, is mapped to the id parameter of the action. Bu örnekte, denetleyici bir ID parametresi ve biri parametresi olmayan iki GET yöntemini tanımlar.In this example, the controller defines two GET methods, one with an id parameter and one with no parameters.

Ayrıca, denetleyici bir " Post... yöntemi tanımlamadığı IÇIN POST isteğinin başarısız olacağını unutmayın " .Also, note that the POST request will fail, because the controller does not define a "Post..." method.

Yönlendirme çeşitlemeleriRouting Variations

Önceki bölümde ASP.NET Web API 'SI için temel yönlendirme mekanizması açıklanmaktadır.The previous section described the basic routing mechanism for ASP.NET Web API. Bu bölümde bazı Çeşitlemeler açıklanmaktadır.This section describes some variations.

HTTP fiilleriHTTP verbs

HTTP fiilleri için adlandırma kuralını kullanmak yerine, eylem yöntemini aşağıdaki özniteliklerden biriyle dekoratarak bir eylem için HTTP fiilini açık bir şekilde belirtebilirsiniz:Instead of using the naming convention for HTTP verbs, you can explicitly specify the HTTP verb for an action by decorating the action method with one of the following attributes:

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

Aşağıdaki örnekte, FindProduct YÖNTEMI get istekleri ile eşlenir:In the following example, the FindProduct method is mapped to GET requests:

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

Bir eylem için birden çok HTTP fiillerine izin vermek veya GET, PUT, POST, DELETE, HEAD, OPTIONS ve PATCH dışındaki HTTP fiillerine izin vermek için, [AcceptVerbs] http fiillerinin bir listesini alan özniteliğini kullanın.To allow multiple HTTP verbs for an action, or to allow HTTP verbs other than GET, PUT, POST, DELETE, HEAD, OPTIONS, and PATCH, use the [AcceptVerbs] attribute, which takes a list of HTTP verbs.

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

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

Eylem adına göre yönlendirmeRouting by Action Name

Varsayılan yönlendirme şablonuyla, Web API 'SI eylemi seçmek için HTTP fiilini kullanır.With the default routing template, Web API uses the HTTP verb to select the action. Bununla birlikte, işlem adının URI 'ye dahil edildiği bir yol da oluşturabilirsiniz:However, you can also create a route where the action name is included in the URI:

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

Bu yol şablonunda, {Action} parametresi denetleyicisindeki eylem yöntemini adlandırır.In this route template, the {action} parameter names the action method on the controller. Bu yönlendirme stili ile, izin verilen HTTP fiillerini belirtmek için özniteliklerini kullanın.With this style of routing, use attributes to specify the allowed HTTP verbs. Örneğin, denetleyicinizin aşağıdaki yöntemi olduğunu varsayalım:For example, suppose your controller has the following method:

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

Bu durumda, "API/ürünler/Ayrıntılar/1" için bir GET isteği Details yöntemine eşlenir.In this case, a GET request for "api/products/details/1" would map to the Details method. Bu yönlendirme stili ASP.NET MVC ile benzerdir ve bir RPC stili API 'SI için uygun olabilir.This style of routing is similar to ASP.NET MVC, and may be appropriate for an RPC-style API.

Özniteliğini kullanarak eylem adını geçersiz kılabilirsiniz [ActionName] .You can override the action name by using the [ActionName] attribute. Aşağıdaki örnekte, " API/ürünler/küçük resim/kimlikile eşlenen iki eylem vardır. Bunlardan biri GET 'i destekler ve diğeri GÖNDERISINI destekler:In the following example, there are two actions that map to "api/products/thumbnail/id. One supports GET and the other supports POST:

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

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

Eylem dışıNon-Actions

Bir yöntemin eylem olarak çağrılmasını engellemek için [NonAction] özniteliğini kullanın.To prevent a method from getting invoked as an action, use the [NonAction] attribute. Bu, başka bir işlem yönlendirme kurallarıyla eşleşse bile, yöntemin bir eylem olmadığı çerçeveye işaret eder.This signals to the framework that the method is not an action, even if it would otherwise match the routing rules.

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

Daha Fazla BilgiFurther Reading

Bu konu, yönlendirmenin üst düzey bir görünümünü sağladı.This topic provided a high-level view of routing. Daha fazla ayrıntı için bkz. Yönlendirme ve eylem seçimi; bu, ÇERÇEVENIN bir URI ile bir yol ile nasıl eşleştiğini açıklar, bir denetleyiciyi seçer ve ardından çağrılacak eylemi seçer.For more detail, see Routing and Action Selection, which describes exactly how the framework matches a URI to a route, selects a controller, and then selects the action to invoke.