ASP.NET Web API'sinde yönlendirme

Bu makalede, ASP.NET Web API'lerinin HTTP isteklerini denetleyicilere nasıl yönlendirdiği açıklanmaktadır.

Uyarı

ASP.NET MVC hakkında bilgi sahibiyseniz, Web API yönlendirmesi MVC yönlendirmesine çok benzer. Asıl fark, Web API'sinin eylemi seçmek için URI yolunu değil HTTP fiilini kullanmasıdır. Web API'sinde MVC stili yönlendirmeyi de kullanabilirsiniz. Bu makalede ASP.NET MVC hakkında herhangi bir bilgi olduğu varsayılmaz.

Yönlendirme Tabloları

ASP.NET Web API'sinde denetleyici , HTTP isteklerini işleyen bir sınıftır. Denetleyicinin genel yöntemleri eylem yöntemleri veya yalnızca eylemler olarak adlandırılır. Web API çerçevesi bir istek aldığında, isteği bir eyleme yönlendirir.

Hangi eylemin çağrıldığını belirlemek için çerçeve bir yönlendirme tablosu kullanır. Web API'sinin Visual Studio proje şablonu varsayılan bir yol oluşturur:

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

Bu yol, App_Start dizinine yerleştirilen WebApiConfig.cs dosyasında tanımlanır:

sınıfı hakkında WebApiConfig daha fazla bilgi için bkz . ASP.NET Web API'sini yapılandırma.

Web API'sini kendi kendine barındırırsanız, yönlendirme tablosunu doğrudan nesne üzerinde HttpSelfHostConfiguration ayarlamanız gerekir. Daha fazla bilgi için bkz. Bir Web API'sini Kendi Kendine Barındırma.

Yönlendirme tablosundaki her giriş bir yol şablonu içerir. Web API'si için varsayılan yol şablonu "api/{controller}/{id}" şeklindedir. Bu şablonda "api" değişmez bir yol bölümüdür ve {controller} ve {id} yer tutucu değişkenleridir.

Web API çerçevesi bir HTTP isteği aldığında, URI'yi yönlendirme tablosundaki yol şablonlarından biriyle eşleştirmeye çalışır. Yol eşleşmezse istemci 404 hatası alır. Örneğin, aşağıdaki URI'ler varsayılan yol ile eşleşer:

• /api/kişiler
• /api/contacts/1
• /api/products/gizmo1

Ancak, "api" kesimi eksik olduğundan aşağıdaki URI eşleşmiyor:

• /contacts/1

Uyarı

Yolda "api" kullanmanın nedeni, ASP.NET MVC yönlendirmesiyle çakışmaları önlemektir. Bu şekilde, "/kişiler" bir MVC denetleyicisine, "/api/kişiler" ise bir Web API denetleyicisine gidebilir. Elbette, bu kuralı beğenmezseniz varsayılan yol tablosunu değiştirebilirsiniz.

Eşleşen bir yol bulunduktan sonra Web API'si denetleyiciyi ve eylemi seçer:

• Denetleyiciyi bulmak için Web API'si {controller} değişkeninin değerine "Denetleyici" ekler.
• Eylemi bulmak için Web API'si HTTP fiiline bakar ve ardından adı bu HTTP fiili adıyla başlayan bir eylemi arar. Örneğin, bir GET isteğiyle, Web API "GetContact" veya "GetAllContacts" gibi "Get" önekiyle başlayan bir işlem arar. Bu kural yalnızca GET, POST, PUT, DELETE, HEAD, OPTIONS ve PATCH fiilleri için geçerlidir. Denetleyicinizdeki öznitelikleri kullanarak diğer HTTP fiillerini etkinleştirebilirsiniz. Bunun bir örneğini daha sonra göreceğiz.
• Yol şablonundaki {id} gibi diğer yer tutucu değişkenler eylem parametreleriyle eşlenir.

Bir örneğe bakalım. Aşağıdaki denetleyiciyi tanımladığınız varsayın:

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

Her bir için çağrılan eylemin yanı sıra bazı olası HTTP istekleri şunlardır:

HTTP Yöntemi	URI Yolu	Eylem	Parametre
GET	api/ürünler	GetAllProducts	(yok)
GET	api/products/4	GetProductById	4
SİLMEK	api/products/4	Ürünü Sil	4
PAYLAŞ	api/ürünler	(eşleşme yok)

Varsa URI'nin {id} kesiminin eylemin id parametresine eşlendiğine dikkat edin. Bu örnekte denetleyici, biri id parametresi ve diğeri parametresiz olmak üzere iki GET yöntemini tanımlar.

Ayrıca, denetleyici bir "Post..." yöntemi tanımlamadığından POST isteğinin başarısız olacağını unutmayın.

Yönlendirme Çeşitlemeleri

Önceki bölümde ASP.NET Web API'sine yönelik temel yönlendirme mekanizması açıklanmıştır. Bu bölümde bazı varyasyonlar açıklanmaktadır.

HTTP eylemleri

HTTP fiilleri için adlandırma kuralını kullanmak yerine, eylem yöntemini aşağıdaki özniteliklerden biriyle süsleyerek bir eylemin HTTP fiilini açıkça belirtebilirsiniz:

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

Aşağıdaki örnekte, FindProduct yöntemi GET isteklerine eşlenmiştir.

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

Bir eylem için birden çok HTTP fiiline izin vermek veya GET, PUT, POST, DELETE, HEAD, OPTIONS ve PATCH dışındaki HTTP fiillerine izin vermek için, HTTP fiillerinin listesini alan özniteliğini kullanın [AcceptVerbs] .

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

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

Eylem Adına Göre Yönlendirme

Varsayılan yönlendirme şablonuyla, Web API eylemi seçmek için HTTP fiilini kullanır. Ancak, eylem adının URI'ye eklendiği bir yol da oluşturabilirsiniz:

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

Bu yol şablonunda {action} parametresi, denetleyicideki eylem metodunun adını belirtir. Bu yönlendirme stiliyle, izin verilen HTTP fiillerini belirtmek için öznitelikleri kullanın. Örneğin, denetleyicinizin aşağıdaki yönteme sahip olduğunu varsayalım:

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

Bu durumda, "api/products/details/1" için bir GET isteği Details yöntemine eşlenecektir. Bu yönlendirme stili ASP.NET MVC'ye benzer ve RPC stili api için uygun olabilir.

özniteliğini kullanarak [ActionName] eylem adını geçersiz kılabilirsiniz. Aşağıdaki örnekte, "api/products/thumbnail/id" ile eşleşen iki eylem vardır. Biri GET'i, diğeri POST'yi destekler:

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

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

Eylemsizlikler

Bir yöntemin eylem olarak çağrılmasını önlemek için özniteliğini [NonAction] kullanın. Bu, yöntemin yönlendirme kurallarıyla eşleşse bile bir eylem olmadığını çerçeveye bildirir.

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

Daha Fazla Okuma

Bu konuda yönlendirmeye yüksek seviyede bir bakış sağlanmıştır. Daha fazla ayrıntı için bkz. Çerçevenin bir URI'yi bir yolla tam olarak nasıl eşleştirdiğini açıklayan Yönlendirme ve Eylem Seçimi, bir denetleyici seçer ve ardından çağrılacak eylemi seçer.