ASP.NET Core'de denetleyici eylemlerine yönlendirme

Ryan Nowak, Kirk Larkin ve Rick Anderson tarafından

ASP.NET Core denetleyicileri, gelen isteklerin URL'lerini eşleştirmek ve bunları actions ile eşlemek için Yönlendirme middleware kullanır. Yol şablonları:

• Başlangıçta Program.cs veya özniteliklerde tanımlanır.
• URL yollarının eylemlerle nasıl eşlendiğini açıklayın.
• Bağlantılar için URL'ler oluşturmak için kullanılır. Oluşturulan bağlantılar genellikle yanıt olarak döndürülür.

Eylemler geleneksel olarak yönlendirilir veya öznitelik tarafından yönlendirilir. Denetleyiciye veya eyleme bir yol yerleştirmek, denetleyicinin öznitelik yönlendirmeli olmasını sağlar. Daha fazla bilgi için bkz. Karma yönlendirme.

Bu belge:

• MVC ile yönlendirme arasındaki etkileşimleri açıklar:
  • Tipik MVC uygulamalarının yönlendirme özelliklerinden nasıl yararlandığından.
  • Her ikisini de kapsar:
    • Geleneksel yönlendirme genellikle denetleyiciler ve görünümlerle kullanılır.
    • Öznitelik yönlendirmesi, REST API’lerle kullanılır. Öncelikli olarak API'ler için yönlendirmeyle ilgileniyorsanız API'ler için RESTREST öznitelik yönlendirme bölümüne atlayın.
  • Gelişmiş yönlendirme ayrıntıları için Yönlendirme bölümüne bakın.
• Varsayılan yönlendirme sistemini uç nokta yönlendirmesi olarak ifade eder. Uyumluluk amacıyla denetleyicileri yönlendirmenin önceki sürümüyle kullanabilirsiniz. Yönergeler için 2.2-3.0 geçiş kılavuzuna bakın.

Geleneksel rotayı ayarlama

ASP.NET Core MVC şablonu, aşağıdaki örneğe benzer konak yönlendirme kodu oluşturur:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Tek bir yol oluşturmak için kullanın MapControllerRoute . Tek rota, default rotasıdır. Denetleyicileri ve görünümleri olan çoğu uygulama, yola benzer default bir yol şablonu kullanır. RESTAPI'ler öznitelik yönlendirme kullanmalıdır.

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Yol şablonu "{controller=Home}/{action=Index}/{id?}":

• /Products/Details/5 gibi bir URL yolunu eşleştirir

• Yolu belirteçleştirerek yol değerlerini ayıklar { controller = Products, action = Details, id = 5 } . Uygulamada ProductsController adlı bir denetleyici ve Details adlı bir eylem varsa, yol değerlerinin çıkarılması bir eşleşmeyle sonuçlanır:

  public class ProductsController : Controller
  {
      public IActionResult Details(int id)
      {
          return ControllerContext.MyDisplayRouteInfo(id);
      }
  }
  

  MyDisplayRouteInfo, Rick.Docs.Samples.RouteInfo NuGet paketi tarafından sağlanır ve yol bilgilerini görüntüler.

• /Products/Details/5 model, id = 5 parametresini id olarak ayarlamak için 5 değerini bağlar. Daha fazla bilgi için bkz. Model Bağlama.

• {controller=Home}varsayılan Homeolarak tanımlarcontroller.

• {action=Index}varsayılan Indexolarak tanımlaraction.

• ? içindeki {id?} karakteri, id öğesinin isteğe bağlı olduğunu belirtir.

  • Varsayılan ve isteğe bağlı yol parametrelerinin eşleşme için URL yolunda mevcut olması gerekmez. Yol şablonu söz diziminin ayrıntılı açıklaması için bkz. Yol Şablonu Başvurusu.

• URL yolu / ile eşleşir.

• Yol değerlerini üretir { controller = Home, action = Index }.

için değerler controller ve action varsayılan değerleri kullanır. id URL yolunda karşılık gelen bir kesim olmadığından bir değer üretmez. / yalnızca bir HomeController ve Index eylemi varsa eşleşir:

public class HomeController : Controller
{
    public IActionResult Index() { ... }
}

Önceki denetleyici tanımını ve yol şablonunu kullanarak, HomeController.Index eylem aşağıdaki URL yolları için çalışır:

• /Home/Index/17
• /Home/Index
• /Home
• /

URL yolu / , rota şablonu varsayılan Home denetleyicisini ve Index eylemini kullanır. URL yolu /Home , rota şablonu varsayılan Index eylemini kullanır.

Kolaylık yöntemi MapDefaultControllerRoute:

app.MapDefaultControllerRoute();

Replaces:

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Important

Yönlendirme, UseRouting ve UseEndpoints ara yazılımları kullanılarak yapılandırılır. Denetleyicileri kullanmak için:

• MapControllers öğesini, öznitelikle yönlendirilen denetleyicileri eşlemek için çağırın.
• Hem MapControllerRoute denetleyicileri hem de MapAreaControllerRoute denetleyicileri eşlemek için veya çağırın.

Uygulamaların genellikle UseRouting veya UseEndpoints çağırmasına gerek yoktur. WebApplicationBuilder, Program.cs içinde eklenen ara yazılımı, UseRouting ve UseEndpoints kullanarak sarmalayan bir ara yazılım işlem hattı yapılandırır. Daha fazla bilgi için ASP.NET Core'da Yönlendirme konusuna bakın.

Geleneksel yönlendirme

Denetleyiciler ve görünümlerle geleneksel yönlendirmeyi kullanın. Yol default şu şekildedir:

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Yukarıdaki kod, geleneksel bir yol örneğidir. URL yolları için bir kural oluşturduğundan buna geleneksel yönlendirme adı verilir:

• İlk yol segmenti olan {controller=Home}, denetleyici adına karşılık gelir.
• İkinci bölüm olan {action=Index}, action adına karşılık gelir.
• Üçüncü segment, isteğe bağlı bir {id?} için kullanılır id. ? içindeki {id?}, bunu isteğe bağlı hâle getirir. id bir model varlığıyla eşlenir.

Bu default rotasını kullanarak URL yolu:

• /Products/List, ProductsController.List eylemine karşılık gelir.
• /Blog/Article/17, BlogController.Article ile eşlenir ve model genellikle id parametresini 17 değerine bağlar.

Bu haritalama:

• Denetleyici ve eylem adlarını yalnızca temel alır.
• Ad alanları, kaynak dosya konumları veya yöntem parametreleri temel alınamaz.

Varsayılan yol ile geleneksel yönlendirmeyi kullanarak, her eylem için yeni bir URL deseni oluşturmanız gerekmez. CRUD tarzı işlemlere sahip bir uygulama için, denetleyiciler genelinde URL'lerde tutarlılığın olması:

• Kodu basitleştirmeye yardımcı olur.
• Kullanıcı arabirimini daha öngörülebilir hale getirir.

Warning

Yol şablonu, id öğesini isteğe bağlı olarak tanımlar. Eylemler, URL'nin parçası olarak sağlanan isteğe bağlı kimlik olmadan yürütülebilir. Genellikle, id URL'den çıkarıldığında:

• Model bağlama, id öğesini 0 olarak ayarlar.
• veritabanında eşleşen id == 0varlık bulunamadı.

Öznitelik yönlendirmesi, bazı eylemler için kimliği zorunlu kılıp diğerleri için zorunlu kılmamak üzere ince ayarlı denetim sağlar. Kural gereği, belgelerde doğru kullanımda görünme olasılıkları gibi id isteğe bağlı parametreler bulunur.

Çoğu uygulama, URL'lerin okunabilir ve anlamlı olması için temel ve açıklayıcı bir yönlendirme düzeni seçmelidir. Varsayılan geleneksel yol {controller=Home}/{action=Index}/{id?}:

• Temel ve açıklayıcı bir yönlendirme düzenini destekler.
• Kullanıcı arabirimi tabanlı uygulamalar için yararlı bir başlangıç noktasıdır.
• Birçok web kullanıcı arabirimi uygulaması için gereken tek yol şablonudur. Daha büyük web kullanıcı arabirimi uygulamaları için, Alanlar'ı kullanan başka bir yol genellikle gereken tek yoldur.

MapControllerRoute ve MapAreaRoute :

• Çağrılma sıralarına göre uç noktalarına otomatik olarak bir sıra değeri atamak.

ASP.NET Core uç nokta yönlendirme:

• Rota kavramı yoktur.
• Genişletilebilirlik yürütme için sipariş garantisi sağlamaz. Tüm uç noktalar aynı anda işlenir.

Günlüğe Kaydetme özelliğini, Route gibi yerleşik yönlendirme uygulamalarının isteklerle nasıl eşleştiğini görmek için etkinleştirin.

Öznitelik yönlendirmesi bu belgenin ilerleyen bölümlerinde açıklanmıştır.

Birden çok geleneksel rota

ve MapControllerRoute için daha fazla çağrı ekleyerek birden çok MapAreaControllerRoute yapılandırabilirsiniz. Bu çağrıları eklediğinizde, birden çok kural tanımlayabilir veya belirli bir eyleme ayrılmış geleneksel yollar ekleyebilirsiniz, örneğin:

app.MapControllerRoute(name: "blog",
                pattern: "blog/{*article}",
                defaults: new { controller = "Blog", action = "Article" });
app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

blog Yukarıdaki koddaki yol, ayrılmış bir geleneksel yoldur. Bu özel bir geleneksel yol çünkü:

• Geleneksel yönlendirme kullanır.
• Belirli bir eyleme ayrılmıştır.

Yol şablonu "blog/{*article}", controller ve action parametre olarak içermediğinden:

• Yalnızca varsayılan değerlerine { controller = "Blog", action = "Article" }sahip olabilirler.
• Bu yol her zaman BlogController.Article eylemine eşlenir.

/Blog, /Blog/Articleve /Blog/{any-string} blog yoluyla eşleşen tek URL yollarıdır.

Yukarıdaki örnekte:

• blog rotası, onu önce eklediğiniz için eşleşmelerde default rotasından daha yüksek önceliğe sahiptir.
• Url'nin bir parçası olarak makale adının olması normal olan Slug stili yönlendirme örneğidir.

Warning

ASP.NET Core'da yönlendirme şunları yapmaz:

• Yol olarak adlandırılan bir kavram tanımlayın. UseRouting ara yazılım işlem hattına yol eşleştirmesi ekler. Ara UseRouting yazılım, uygulamada tanımlanan uç nokta kümesine bakar ve isteğe göre en iyi uç nokta eşleşmesini seçer.
• IRouteConstraint veya IActionConstraint gibi genişletilebilirliklerin yürütme sırası konusunda garanti sağlar.

Yönlendirmeyle ilgili başvuru bilgileri için Yönlendirme bölümüne bakın.

Geleneksel yönlendirme sırası

Geleneksel yönlendirme yalnızca uygulamanın tanımladığı eylem ve denetleyici birleşimiyle eşleşir. Bu yaklaşım, geleneksel yolların çakıştığı durumları basitleştirir. MapControllerRoute, MapDefaultControllerRoute ve MapAreaControllerRoute kullanarak rotalar eklediğinizde, uç noktalara bu yöntemleri çağırdığınız sıraya göre otomatik olarak bir sıralama değeri atanır. Listede daha önce görünen bir rotadaki eşleşmelerin önceliği daha yüksektir. Geleneksel yönlendirme, siparişe bağlıdır. Genel olarak, öncelikle alanları içeren rotaları, alan içermeyen rotalardan daha belirgin oldukları için yerleştirin. Özel geleneksel rotalar, {*article} gibi catch-all rota parametreleriyle, bir rotayı fazla aşırı kapsayıcı hâle getirebilir. Açgözlü bir rota, başka rotalar tarafından eşlenmesi amaçlanan URL'lerle eşleşir. Açgözlü eşleşmeleri önlemek için açgözlü yolları yol tablosuna daha geç ekleyin.

Belirsiz eylemleri çözme

yönlendirme aracılığıyla iki uç nokta eşleştiğinde, yönlendirme aşağıdaki adımlardan birini gerçekleştirmelidir:

• En iyi adayı seçin.
• Özel durum oluşturma.

Örneğin:

public class Products33Controller : Controller
{
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [HttpPost]
    public IActionResult Edit(int id, Product product)
    {
        return ControllerContext.MyDisplayRouteInfo(id, product.name);
    }
}

Yukarıdaki denetleyici, eşleşen iki eylemi tanımlar:

• URL yolu /Products33/Edit/17
• Yönlendirme verileri { controller = Products33, action = Edit, id = 17 }.

Bu, MVC denetleyicileri için tipik bir desendir:

• Edit(int) bir ürünü düzenlemek için bir form görüntüler.
• Edit(int, Product) gönderilen formu işler.

Doğru yolu çözümlemek için:

• Edit(int, Product) , istek bir HTTP POSTolduğunda seçilir.
• Edit(int), HTTP fiili başka bir şey olduğunda seçilir. Edit(int), genellikle GET aracılığıyla çağrılır.

HttpPostAttribute, [HttpPost], isteğin HTTP yöntemine göre seçim yapabilmesi için yönlendirmeye iletilir. HttpPostAttribute, Edit(int, Product)'i Edit(int)'den daha iyi bir eşleşme yapar.

gibi HttpPostAttributeözniteliklerin rolünü anlamak önemlidir. Diğer HTTP fiilleri için benzer öznitelikler tanımlanır. Geleneksel yönlendirmede, eylemler formu gösterme ve gönderme iş akışının parçası olduklarında genellikle aynı eylem adını kullanır. Örneğin, iki Edit eylem yöntemini inceleyin.

Yönlendirme en iyi adayı seçemiyorsa, bir AmbiguousMatchException oluşturur ve eşleşen birden çok uç noktayı listeler.

Geleneksel yol adları

Aşağıdaki örneklerde "blog" ve "default" dizeleri geleneksel rota adlarıdır:

app.MapControllerRoute(name: "blog",
                pattern: "blog/{*article}",
                defaults: new { controller = "Blog", action = "Article" });
app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

Yol adları, yola mantıksal bir ad verir. Adlandırılmış yol, URL oluşturma için kullanılabilir. Adlandırılmış yol kullanmak, yolların sıralanması URL oluşturmayı karmaşık hale getirebileceğinden URL oluşturmayı kolaylaştırır. Yol adları, uygulama genelinde benzersiz olmalıdır.

Yol adları:

• URL eşleştirme veya istekleri işleme üzerinde hiçbir etkisi yoktur.
• Yalnızca URL oluşturma için kullanılır.

Yol adı kavramı, yönlendirmede IEndpointNameMetadata olarak temsil edilir. Yol adı ve uç nokta adı terimleri:

• Bunlar birbirinin yerine kullanılabilir.
• Belgelerde ve kodlarda hangisinin kullanıldığı, açıklanan API'ye bağlıdır.

REST API'leri için öznitelik tabanlı yönlendirme

RESTAPI'ler, işlemlerin HTTP fiilleri ile temsil edildiği bir kaynak kümesi olarak uygulamanın işlevselliğini modellemek için öznitelik yönlendirmesini kullanmalıdır.

Öznitelik yönlendirme, eylemleri doğrudan yol şablonlarıyla eşlemek için bir dizi öznitelik kullanır. Aşağıdaki kod bir REST API için tipiktir ve sonraki örnekte kullanılır:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Önceki kodda, öznitelik yönlendirmeli denetleyicileri eşlemek için MapControllers çağrısı yaparsınız.

Aşağıdaki örnekte:

• HomeController , varsayılan geleneksel yolun {controller=Home}/{action=Index}/{id?} eşlediği url'lere benzer bir URL kümesiyle eşleşir.

public class HomeController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult Index(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult About(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

HomeController.Index eylemi, /, /Home, /Home/Index veya /Home/Index/3 URL yollarından herhangi biri için çalışır.

Bu örnek, öznitelik yönlendirmesi ile geleneksel yönlendirme arasındaki temel programlama farkını vurgular. Öznitelik yönlendirmesi, yol belirtmek için daha fazla giriş gerektirir. Geleneksel varsayılan yol, yolları daha özlü ve etkili bir şekilde yönetir. Ancak, öznitelik yönlendirmesi her eylem için hangi yol şablonlarının geçerli olduğunu hassas bir şekilde denetlemenizi sağlar ve gerektirir.

Öznitelik yönlendirmede, token değiştirme kullanılmadığı sürece, denetleyici ve eylem adları hangi eylemin eşleştirileceğinde rol oynamaz. Aşağıdaki örnek, önceki örnekle aynı URL'ler ile eşleşir:

public class MyDemoController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult MyIndex(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult MyAbout(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Aşağıdaki kod, action ve controller için belirteç değiştirmesini kullanır:

public class HomeController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("[controller]/[action]")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [Route("[controller]/[action]")]
    public IActionResult About()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Aşağıdaki kod denetleyici için geçerlidir [Route("[controller]/[action]")] :

[Route("[controller]/[action]")]
public class HomeController : Controller
{
    [Route("~/")]
    [Route("/Home")]
    [Route("~/Home/Index")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    public IActionResult About()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Yukarıdaki kodda, Index yöntem şablonları, yol şablonlarının başına / veya ~/ eklemelidir. Bir eyleme uygulanan ve / veya ~/ ile başlayan yönlendirme şablonları, denetleyiciye uygulanan yönlendirme şablonlarıyla birleştirilmez.

Rota şablonu seçimi hakkında bilgi için bkz . Yol şablonu önceliği .

Ayrılmış yönlendirme adları

Denetleyiciler veya Razor Sayfalar kullandığınızda aşağıdaki anahtar sözcükler ayrılmış yol parametre adlarıdır:

• action
• area
• controller
• handler
• page

Öznitelik yönlendirme ile yol parametresi olarak kullanmak page yaygın bir hatadır. Bu seçim, URL oluşturma ile tutarsız ve kafa karıştırıcı davranışlara neden olur.

public class MyDemo2Controller : Controller
{
    [Route("/articles/{page}")]
    public IActionResult ListArticles(int page)
    {
        return ControllerContext.MyDisplayRouteInfo(page);
    }
}

URL oluşturma, URL oluşturma işleminin Sayfaya mı yoksa Denetleyiciye mi başvurduğuna karar vermek için Razor bu özel parametre adlarını kullanır.

Aşağıdaki anahtar sözcükler bir Razor görünüm veya Razor Sayfa bağlamında ayrılmıştır:

• page
• using
• namespace
• inject
• section
• inherits
• model
• addTagHelper
• removeTagHelper

Bağlantı nesilleri, modele bağlı parametreler veya en üst düzey özellikler için bu anahtar sözcükleri kullanmayın.

HTTP fiil şablonları

ASP.NET Core aşağıdaki HTTP fiili şablonlarını içerir:

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

Yol şablonları

ASP.NET Core aşağıdaki yol şablonlarını içerir:

• Tüm HTTP fiil şablonları yol şablonlarıdır.
• [Route]

HTTP fiil öznitelikleriyle öznitelik yönlendirme

Aşağıdaki denetleyiciyi göz önünde bulundurun:

[Route("api/[controller]")]
[ApiController]
public class Test2Controller : ControllerBase
{
    [HttpGet]   // GET /api/test2
    public IActionResult ListProducts()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("{id}")]   // GET /api/test2/xyz
    public IActionResult GetProduct(string id)
    {
       return ControllerContext.MyDisplayRouteInfo(id);
    }

    [HttpGet("int/{id:int}")] // GET /api/test2/int/3
    public IActionResult GetIntProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [HttpGet("int2/{id}")]  // GET /api/test2/int2/3
    public IActionResult GetInt2Product(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Önceki kodda:

• Her eylem, eşleştirmeyi yalnızca HTTP GET istekleriyle sınırlayan [HttpGet] özniteliğini içerir.
• Eylem GetProduct şablonu içerdiğinden "{id}" , denetleyicideki id şablonun "api/[controller]" sonuna eklenir. Yöntemin şablonu şeklindedir "api/[controller]/{id}". Bu nedenle bu eylem yalnızca /api/test2/xyz, /api/test2/123, /api/test2/{any string} vb. biçimindeki GET istekleriyle eşleşir.

  [HttpGet("{id}")]   // GET /api/test2/xyz
  public IActionResult GetProduct(string id)
  {
     return ControllerContext.MyDisplayRouteInfo(id);
  }
  

• GetIntProduct eylemi "int/{id:int}" şablonunu içerir. Şablonun :int bölümü, yol değerlerini tamsayıya dönüştürülebilecek dizelerle kısıtlar id . /api/test2/int/abc için bir GET isteği:
  • Bu eylemle eşleşmiyor.
  • 404 Bulunamadı hatası döndürür.

    [HttpGet("int/{id:int}")] // GET /api/test2/int/3
    public IActionResult GetIntProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
    

• GetInt2Product eylemi şablonda {id} içerir, ancak id değerini tamsayıya dönüştürülebilen değerlerle kısıtlamaz. /api/test2/int2/abc için bir GET isteği:
  • Bu rota ile eşleşir.
  • Model bağlama, abc değerini tamsayıya dönüştüremiyor. id yönteminin parametresi tamsayıdır.
  • Model bağlama, öğesini bir tamsayıya dönüştüremediği için abc döndürür.

    [HttpGet("int2/{id}")]  // GET /api/test2/int2/3
    public IActionResult GetInt2Product(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
    

Öznitelik tabanlı yönlendirme, HttpMethodAttribute, HttpPostAttribute, HttpPutAttribute ve HttpDeleteAttribute gibi öznitelikleri kullanabilir. Tüm HTTP fiil öznitelikleri bir yol şablonu kabul eder. Aşağıdaki örnekte aynı yol şablonuyla eşleşen iki eylem gösterilmektedir:

[ApiController]
public class MyProductsController : ControllerBase
{
    [HttpGet("/products3")]
    public IActionResult ListProducts()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpPost("/products3")]
    public IActionResult CreateProduct(MyProduct myProduct)
    {
        return ControllerContext.MyDisplayRouteInfo(myProduct.Name);
    }
}

/products3 URL yolunu kullanarak:

• MyProductsController.ListProducts eylemi, HTTP fiiliGET olduğunda çalışır.
• MyProductsController.CreateProduct eylemi, HTTP fiiliPOST olduğunda çalışır.

Bir REST API oluştururken, action tüm HTTP yöntemlerini kabul ettiğinden, bir action yönteminde [Route(...)] kullanmanız nadiren gerekir. API'nizin neleri desteklediği konusunda kesin olmak için daha özel HTTP fiil özniteliğini kullanın. REST API’lerinin istemcilerinin, hangi yolların ve HTTP eylemlerinin belirli mantıksal işlemlere karşılık geldiğini bilmesi beklenir.

REST API'ler, işlemlerin HTTP fiilleri ile temsil edildiği bir kaynak kümesi olarak uygulamanın işlevselliğini modellemek için öznitelik yönlendirmesini kullanmalıdır. Bu tasarım, aynı mantıksal kaynakta GET ve POST gibi birçok işlemin aynı URL'yi kullandığı anlamına gelir. Öznitelik yönlendirme, bir API'nin genel uç nokta düzenini dikkatle tasarlamak için gereken denetim düzeyini sağlar.

Öznitelik yolu belirli bir eyleme uygulandığından, yol şablonu tanımının bir parçası olarak gerekli parametreleri yapmak kolaydır. Aşağıdaki örnekte, id URL yolunun bir parçası olarak gereklidir:

[ApiController]
public class Products2ApiController : ControllerBase
{
    [HttpGet("/products2/{id}", Name = "Products_List")]
    public IActionResult GetProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Eylem Products2ApiController.GetProduct(int) :

• /products2/3 gibi bir URL yolu ile çalıştırılır
• URL yolu /products2 ile çalıştırılmaz.

[Consumes] özniteliği, desteklenen istek içerik türlerini sınırlamak için bir eyleme izin verir. Daha fazla bilgi için bkz . Consumes özniteliğiyle desteklenen istek içerik türlerini tanımlama.

Rota şablonlarının ve ilgili seçeneklerin tam açıklaması için bkz . Yönlendirme .

[ApiController] hakkında daha fazla bilgi için bkz. ApiController özniteliği.

Yol adı

Aşağıdaki kod, yolunun Products_Listadını tanımlar:

[ApiController]
public class Products2ApiController : ControllerBase
{
    [HttpGet("/products2/{id}", Name = "Products_List")]
    public IActionResult GetProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Belirli bir yolu temel alan bir URL oluşturmak için yol adlarını kullanın. Yol adları:

• Yönlendirmenin URL eşleştirme davranışı üzerinde hiçbir etkisi yoktur.
• Yalnızca URL oluşturma için kullanılır.

Yol adları uygulama genelinde benzersiz olmalıdır.

Önceki kodu, id parametresini isteğe bağlı ({id?}) olarak tanımlayan geleneksel varsayılan rotayla karşılaştırın. API'leri tam olarak belirtebilme özelliği, farklı eylemlere izin verme /products ve /products/5 gönderme gibi avantajlara sahiptir.

Öznitelik yollarını birleştirme

Öznitelik yönlendirmesini daha az yinelenen hale getirmek için, denetleyicideki yol özniteliklerini tek tek eylemlerdeki yol öznitelikleriyle birleştirin. Denetleyicide tanımladığınız yol şablonları, eylemlerdeki yol şablonlarına eklenir. Denetleyiciye bir yol özniteliği yerleştirdiğinizde, denetleyicideki tüm eylemler öznitelik yönlendirmesini kullanır.

[ApiController]
[Route("products")]
public class ProductsApiController : ControllerBase
{
    [HttpGet]
    public IActionResult ListProducts()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("{id}")]
    public IActionResult GetProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Yukarıdaki örnekte:

• URL yolu /products eşleşebilir ProductsApi.ListProducts
• URL yolu /products/5 ile eşleşebilir ProductsApi.GetProduct(int).

Bu iki eylem de, GET özniteliğiyle işaretlendikleri için yalnızca HTTP [HttpGet] ile eşleşir.

Bir eyleme uyguladığınız ve / veya ~/ ile başlayan yol şablonları, denetleyiciye uyguladığınız yol şablonlarıyla birleştirilmez. Aşağıdaki örnek, varsayılan yola benzer bir URL yolu kümesiyle eşleşir.

[Route("Home")]
public class HomeController : Controller
{
    [Route("")]
    [Route("Index")]
    [Route("/")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [Route("About")]
    public IActionResult About()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Aşağıdaki tabloda, önceki koddaki öznitelikler açıklanmaktadır [Route] .

Attribute	[Route("Home")] ile birleştirilir	Yol şablonunu tanımlar
[Route("")]	Yes	"Home"
[Route("Index")]	Yes	"Home/Index"
[Route("/")]	Hayır	""
[Route("About")]	Yes	"Home/About"

Öznitelik yönlendirme sırası

Yönlendirme bir ağaç oluşturur ve tüm uç noktaları aynı anda eşleştirir:

• Yol girişleri, ideal bir sıralamaya yerleştirilmiş gibi davranır.
• En özel rotalar, daha genel rotalardan önce çalıştırılma olasılığına sahiptir.

Örneğin, blog/search/{topic} gibi bir öznitelik yolu, blog/{*article} gibi bir öznitelik yolundan daha özeldir. Rota blog/search/{topic} daha belirgin olduğundan varsayılan olarak daha yüksek önceliğe sahiptir. Geleneksel yönlendirmeyi kullanarak, rotaları istenen sıraya yerleştirmek geliştiricinin sorumluluğundadır.

Öznitelik rotaları, sıralamayı Order özelliğini kullanarak yapılandırabilir. Sağlanan tüm çerçeve yol öznitelikleri içerir Order . Rotalar, Order özelliğine göre artan sıralamayla işlenir. Varsayılan sıra şeklindedir 0. Order = -1 kullanarak bir rota ayarlamak, sıra belirtmeyen rotalardan önce çalışır. Order = 1 kullanarak rota ayarlama, varsayılan rota sıralamasından sonra çalışır.

Order. Bir uygulamanın URL alanı doğru yönlendirmek için açık sipariş değerleri gerektiriyorsa, istemciler için de kafa karıştırıcı olabilir. Genel olarak, öznitelik yönlendirme url eşleştirme ile doğru yolu seçer. URL oluşturma için kullanılan varsayılan sıra çalışmıyorsa, geçersiz kılma olarak yol adı kullanmak genellikle özelliğin Order uygulanmasından daha basittir.

İkisi de /home rota eşleştirmesini tanımlayan aşağıdaki iki denetleyiciyi göz önünde bulundurun:

public class HomeController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult Index(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult About(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

public class MyDemoController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult MyIndex(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult MyAbout(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

/home Yukarıdaki kodu kullanarak istekte bulunmak aşağıdakine benzer bir özel durum oluşturur:

AmbiguousMatchException: The request matched multiple endpoints. Matches:

 WebMvcRouting.Controllers.HomeController.Index
 WebMvcRouting.Controllers.MyDemoController.MyIndex

Yol özniteliklerinden birine eklendiğinde Order belirsizlik çözülür:

[Route("")]
[Route("Home", Order = 2)]
[Route("Home/MyIndex")]
public IActionResult MyIndex()
{
    return ControllerContext.MyDisplayRouteInfo();
}

Önceki kodla, /homeHomeController.Index uç noktasını çalıştırır. MyDemoController.MyIndex öğesine ulaşmak için /home/MyIndex isteğinde bulunun. Not:

• Yukarıdaki kod, kötü yönlendirme tasarımı örneğidir. Order özelliğini gösterir.
• Order özelliği yalnızca belirsizliği giderir. Bu şablon eşleştirilemez. [Route("Home")] şablonunu kaldırmak daha iyidir.

Razor Pages ile rota sırası hakkında bilgi için bkz. Razor Pages rota ve uygulama kuralları: Rota sırası.

Bazı durumlarda, belirsiz yollar içeren bir HTTP 500 hatası döndürülür. Hangi uç noktaların 'a neden olduğunu görmek için AmbiguousMatchException kullanın.

Yol şablonlarında belirteç değiştirme [denetleyici], [eylem], [alan]

Kolaylık sağlamak için öznitelik yolları, belirteci köşeli ayraç içine alarak belirtecin değiştirilmesini destekler ([, ]). , [action]ve [area] belirteçleri[controller], yolu tanımladığınız eylemdeki eylem adı, alan adı ve denetleyici adı değerleriyle değiştirilir:

[Route("[controller]/[action]")]
public class Products0Controller : Controller
{
    [HttpGet]
    public IActionResult List()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }


    [HttpGet("{id}")]
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Önceki kodda:

[HttpGet]
public IActionResult List()
{
    return ControllerContext.MyDisplayRouteInfo();
}

• Eşleşmeler /Products0/List

[HttpGet("{id}")]
public IActionResult Edit(int id)
{
    return ControllerContext.MyDisplayRouteInfo(id);
}

• Eşleşmeler /Products0/Edit/{id}

Belirteç değiştirme, öznitelik yollarını oluşturmanın son adımı olarak gerçekleşir. Yukarıdaki örnek aşağıdaki kodla aynı şekilde davranır:

public class Products20Controller : Controller
{
    [HttpGet("[controller]/[action]")]  // Matches '/Products20/List'
    public IActionResult List()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("[controller]/[action]/{id}")]   // Matches '/Products20/Edit/{id}'
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Bunu İngilizce dışında bir dilde okuyorsanız, kod açıklamalarını ana dilinizde görmek istiyorsanız, bu GitHub tartışma konusunu bize bildirin.

Öznitelik yollarını devralma ile de birleştirebilirsiniz. Token değiştirme kullandığınızda bu kombinasyon güçlüdür. Belirteç değiştirme, öznitelik yolları tarafından tanımlanan yol adları için de geçerlidir. [Route("[controller]/[action]", Name="[controller]_[action]")]her eylem için benzersiz bir yol adı oluşturur:

[ApiController]
[Route("api/[controller]/[action]", Name = "[controller]_[action]")]
public abstract class MyBase2Controller : ControllerBase
{
}

public class Products11Controller : MyBase2Controller
{
    [HttpGet]                      // /api/products11/list
    public IActionResult List()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("{id}")]             //    /api/products11/edit/3
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Değişmez değer belirteci değiştirme sınırlayıcısı [ veya ]ile eşleştirmek için karakteri ([[ veya ]]) yineleyerek bu sınırlayıcıdan kaçın.

Belirteç değişimini özelleştirmek için parametre transformatörü kullanma

Parametre transformatörü kullanarak belirteç değişimini özelleştirebilirsiniz. Parametre transformatörü parametrelerin IOutboundParameterTransformer değerini uygular ve dönüştürür. Örneğin, özel bir SlugifyParameterTransformer parametre dönüştürücüsü SubscriptionManagement rota değerini subscription-management olarak değiştirir:

using System.Text.RegularExpressions;

public class SlugifyParameterTransformer : IOutboundParameterTransformer
{
    public string? TransformOutbound(object? value)
    {
        if (value == null) { return null; }

        return Regex.Replace(value.ToString()!,
                             "([a-z])([A-Z])",
                             "$1-$2",
                             RegexOptions.CultureInvariant,
                             TimeSpan.FromMilliseconds(100)).ToLowerInvariant();
    }
}

RouteTokenTransformerConvention, aşağıdakilere sahip bir uygulama modeli kuralıdır:

• Bir uygulamadaki tüm öznitelik yollarına parametre transformatörü uygulayın.
• Öznitelik yol belirteci değerlerini değiştirme sırasında özelleştirir.

public class SubscriptionManagementController : Controller
{
    [HttpGet("[controller]/[action]")]
    public IActionResult ListAll()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Önceki ListAll yöntem, /subscription-management/list-all ile eşleşir.

RouteTokenTransformerConvention seçeneği olarak kaydedilir:

using Microsoft.AspNetCore.Mvc.ApplicationModels;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews(options =>
{
    options.Conventions.Add(new RouteTokenTransformerConvention(
                                 new SlugifyParameterTransformer()));
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Slug tanımı için MDN Web Docs'taki Slug belgesine bakın.

Warning

Güvenilmeyen verileri işlemek için System.Text.RegularExpressions kullanırken bir zaman aşımı süresi belirtin. Kötü amaçlı bir kullanıcı, RegularExpressions girdileri sağlayarak bir Hizmet Reddi saldırısına neden olabilir. RegularExpressions kullanan ASP.NET Core çerçeve API'leri zaman aşımına neden olur.

Birden çok öznitelik yolu

Öznitelik yönlendirme, aynı eyleme ulaşan birden çok yol tanımlamayı destekler. Bunun en yaygın kullanımı, aşağıdaki örnekte gösterildiği gibi varsayılan geleneksel yolun davranışını taklit etmektir:

[Route("[controller]")]
public class Products13Controller : Controller
{
    [Route("")]     // Matches 'Products13'
    [Route("Index")] // Matches 'Products13/Index'
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

Denetleyiciye birden çok yol özniteliği koymak, her birinin eylem yöntemlerindeki yol özniteliklerinin her biriyle birleştirilmesi anlamına gelir:

[Route("Store")]
[Route("[controller]")]
public class Products6Controller : Controller
{
    [HttpPost("Buy")]       // Matches 'Products6/Buy' and 'Store/Buy'
    [HttpPost("Checkout")]  // Matches 'Products6/Checkout' and 'Store/Checkout'
    public IActionResult Buy()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Tüm HTTP fiil yolu kısıtlamaları uygularIActionConstraint.

IActionConstraint uygulayan birden çok yol özniteliği bir eylem üzerine yerleştirildiğinde:

• Her eylem kısıtlaması, denetleyiciye uygulanan yol şablonuyla birleştirilir.

[Route("api/[controller]")]
public class Products7Controller : ControllerBase
{
    [HttpPut("Buy")]        // Matches PUT 'api/Products7/Buy'
    [HttpPost("Checkout")]  // Matches POST 'api/Products7/Checkout'
    public IActionResult Buy()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Eylemlerde birden çok yol kullanmak yararlı ve güçlü görünebilir; uygulamanızın URL alanını temel ve iyi tanımlanmış olarak tutmak daha iyidir. Eylemlerde yalnızca gerektiğinde, örneğin mevcut istemcileri desteklemek için birden çok yol kullanın.

Öznitelik yolu isteğe bağlı parametreleri, varsayılan değerleri ve kısıtlamaları belirtme

Öznitelik yolları isteğe bağlı parametreleri, varsayılan değerleri ve kısıtlamaları belirtmek için geleneksel yollar ile aynı satır içi söz dizimini destekler.

public class Products14Controller : Controller
{
    [HttpPost("product14/{id:int}")]
    public IActionResult ShowProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Yukarıdaki kodda bir [HttpPost("product14/{id:int}")] yol kısıtlaması uygular. Products14Controller.ShowProduct eylemi yalnızca /product14/3 gibi URL yollarıyla eşleştirilir. Yol şablonu bölümü {id:int} , bu segmenti yalnızca tamsayılarla kısıtlar.

Yol şablonu söz diziminin ayrıntılı açıklaması için bkz. Yol Şablonu Başvurusu.

IRouteTemplateProvider kullanan özel yol öznitelikleri

Tüm rota öznitelikleriIRouteTemplateProvider öğesini uygular. ASP.NET Core çalışma zamanı:

• Uygulama başlatıldığında denetleyici sınıflarında ve eylem yöntemlerinde öznitelikleri arar.
• Başlangıç rota kümesini oluşturmak için IRouteTemplateProvider uygulayan öznitelikleri kullanır.

Özel yol özniteliklerini tanımlamak için uygulayın IRouteTemplateProvider . Her IRouteTemplateProvider bir özel yol şablonu, sırası ve adıyla tek bir yol tanımlamanızı sağlar:

public class MyApiControllerAttribute : Attribute, IRouteTemplateProvider
{
    public string Template => "api/[controller]";
    public int? Order => 2;
    public string Name { get; set; } = string.Empty;
}

[MyApiController]
[ApiController]
public class MyTestApiController : ControllerBase
{
    // GET /api/MyTestApi
    [HttpGet]
    public IActionResult Get()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Yukarıdaki Get yöntem döndürür Order = 2, Template = api/MyTestApi.

Öznitelik yollarını özelleştirmek için uygulama modelini kullanma

Uygulama modeli:

• Program.cs içinde başlangıçta oluşturulan bir nesne modelidir.
• bir uygulamada eylemleri yönlendirmek ve yürütmek için ASP.NET Core tarafından kullanılan tüm meta verileri içerir.

Uygulama modeli, yol özniteliklerinden toplanan tüm verileri içerir. Yol özniteliklerindeki veriler uygulama tarafından IRouteTemplateProvider sağlanır. Conventions:

• Yönlendirmenin davranışını özelleştirmek için uygulama modelini değiştirmek için yazılabilir.
• Uygulama başlangıcında okunur.

Bu bölümde, uygulama modelini kullanarak yönlendirmeyi özelleştirmeye yönelik temel bir örnek gösterilmektedir. Aşağıdaki kod, yolları kabaca projenin klasör yapısıyla hizalar.

public class NamespaceRoutingConvention : Attribute, IControllerModelConvention
{
    private readonly string _baseNamespace;

    public NamespaceRoutingConvention(string baseNamespace)
    {
        _baseNamespace = baseNamespace;
    }

    public void Apply(ControllerModel controller)
    {
        var hasRouteAttributes = controller.Selectors.Any(selector =>
                                                selector.AttributeRouteModel != null);
        if (hasRouteAttributes)
        {
            return;
        }

        var namespc = controller.ControllerType.Namespace;
        if (namespc == null)
            return;
        var template = new StringBuilder();
        template.Append(namespc, _baseNamespace.Length + 1,
                        namespc.Length - _baseNamespace.Length - 1);
        template.Replace('.', '/');
        template.Append("/[controller]/[action]/{id?}");

        foreach (var selector in controller.Selectors)
        {
            selector.AttributeRouteModel = new AttributeRouteModel()
            {
                Template = template.ToString()
            };
        }
    }
}

Aşağıdaki kod, kuralın namespace yönlendirilen öznitelik denetleyicilerine uygulanmasını engeller:

public void Apply(ControllerModel controller)
{
    var hasRouteAttributes = controller.Selectors.Any(selector =>
                                            selector.AttributeRouteModel != null);
    if (hasRouteAttributes)
    {
        return;
    }

Örneğin, aşağıdaki denetleyici şunu kullanmaz NamespaceRoutingConvention:

[Route("[controller]/[action]/{id?}")]
public class ManagersController : Controller
{
    // /managers/index
    public IActionResult Index()
    {
        var template = ControllerContext.ActionDescriptor.AttributeRouteInfo?.Template;
        return Content($"Index- template:{template}");
    }

    public IActionResult List(int? id)
    {
        var path = Request.Path.Value;
        return Content($"List- Path:{path}");
    }
}

NamespaceRoutingConvention.Apply yöntemi:

• Denetleyici öznitelik yönlendirildiyse hiçbir şey yapmaz.
• Denetleyiciler şablonunu, temel namespace kaldırılarak namespace temelinde ayarlar.

NamespaceRoutingConvention, Program.cs içinde uygulanabilir:

using My.Application.Controllers;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews(options =>
{
    options.Conventions.Add(
     new NamespaceRoutingConvention(typeof(HomeController).Namespace!));
});

var app = builder.Build();

Örneğin, aşağıdaki denetleyiciyi göz önünde bulundurun:

using Microsoft.AspNetCore.Mvc;

namespace My.Application.Admin.Controllers
{
    public class UsersController : Controller
    {
        // GET /admin/controllers/users/index
        public IActionResult Index()
        {
            var fullname = typeof(UsersController).FullName;
            var template = 
                ControllerContext.ActionDescriptor.AttributeRouteInfo?.Template;
            var path = Request.Path.Value;

            return Content($"Path: {path} fullname: {fullname}  template:{template}");
        }

        public IActionResult List(int? id)
        {
            var path = Request.Path.Value;
            return Content($"Path: {path} ID:{id}");
        }
    }
}

Önceki kodda:

• Taban namespace şeklindedir My.Application.
• Önceki denetleyicinin tam adı şeklindedir My.Application.Admin.Controllers.UsersController.
• NamespaceRoutingConvention, denetleyiciler şablonunu Admin/Controllers/Users/[action]/{id? olarak ayarlar.

, NamespaceRoutingConvention bir denetleyiciye öznitelik olarak da uygulanabilir:

[NamespaceRoutingConvention("My.Application")]
public class TestController : Controller
{
    // /admin/controllers/test/index
    public IActionResult Index()
    {
        var template = ControllerContext.ActionDescriptor.AttributeRouteInfo?.Template;
        var actionname = ControllerContext.ActionDescriptor.ActionName;
        return Content($"Action- {actionname} template:{template}");
    }

    public IActionResult List(int? id)
    {
        var path = Request.Path.Value;
        return Content($"List- Path:{path}");
    }
}

Karma yönlendirme: Öznitelik yönlendirmesi ile geleneksel yönlendirme karşılaştırması

ASP.NET Core uygulamalar geleneksel yönlendirme ve öznitelik yönlendirme kullanımını karıştırabilir. Genellikle tarayıcılara HTML sayfaları sunan denetleyiciler için geleneksel yolları ve API'lere hizmet REST veren denetleyiciler için öznitelik yönlendirmesini kullanırsınız.

Eylemler ya geleneksel olarak ya da öznitelik tabanlı yönlendirilir. Denetleyiciye veya eyleme bir yol tanımladığınızda, öznitelikle yönlendirilmiş olur. Öznitelik yollarını geleneksel yollar üzerinden tanımlayan eylemlere (veya tam tersi) ulaşamazsınız. Denetleyicideki herhangi bir yol özniteliği, denetleyici özniteliğindeki tüm eylemlerin yönlendirilmiş olmasını sağlar.

Öznitelik yönlendirme ve geleneksel yönlendirme aynı yönlendirme altyapısını kullanır.

Özel karakterlerle yönlendirme

Özel karakterlerle yönlendirme beklenmeyen sonuçlara yol açabilir. Örneğin, aşağıdaki eylem yöntemine sahip bir denetleyici düşünün:

[HttpGet("{id?}/name")]
public async Task<ActionResult<string>> GetName(string id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null || todoItem.Name == null)
    {
        return NotFound();
    }

    return todoItem.Name;
}

string id Aşağıdaki kodlanmış değerleri içerdiğinde beklenmeyen sonuçlar oluşabilir:

ASCII	Encoded
/	%2F
	+

Yol parametreleri her zaman URL kodunu çözmez. Bu sorun gelecekte giderilebilir. Daha fazla bilgi için bkz. bu GitHub sorunu;

URL oluşturma ve ortam değerleri

Uygulamalar, eylemlere URL bağlantıları oluşturmak için yönlendirme URL'si oluşturma özelliklerini kullanabilir. URL'lerin oluşturulması sabit kodlama URL'lerini ortadan kaldırarak kodu daha sağlam ve sürdürülebilir hale getirir. Bu bölüm, MVC tarafından sağlanan URL oluşturma özelliklerine odaklanır ve yalnızca URL oluşturmanın nasıl çalıştığına ilişkin temel bilgileri kapsar. URL oluşturmanın ayrıntılı açıklaması için bkz . Yönlendirme .

IUrlHelper Arabirim, MVC ile URL oluşturma için yönlendirme arasındaki altyapının temel öğesidir. IUrlHelper örneği, denetleyicilerde, görünümlerde ve görünüm bileşenlerinde Url özelliği aracılığıyla kullanılabilir.

Aşağıdaki örnekte, IUrlHelper arabirim özelliği aracılığıyla başka bir eylemin Controller.Url URL'sini oluşturmak için kullanılır.

public class UrlGenerationController : Controller
{
    public IActionResult Source()
    {
        // Generates /UrlGeneration/Destination
        var url = Url.Action("Destination");
        return ControllerContext.MyDisplayRouteInfo("", $" URL = {url}");
    }

    public IActionResult Destination()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Uygulama varsayılan geleneksel yolu kullanıyorsa değişkeninin url değeri URL yol dizesidir /UrlGeneration/Destination. Yönlendirme, şu URL yolunu oluşturmak için aşağıdakileri birleştirir:

• Geçerli istekteki rota değerleri, ortam değerleri olarak adlandırılır.
• Url.Action öğesine geçirilen değerler ve bu değerlerin rota şablonunda yerine konulması:

ambient values: { controller = "UrlGeneration", action = "Source" }
values passed to Url.Action: { controller = "UrlGeneration", action = "Destination" }
route template: {controller}/{action}/{id?}

result: /UrlGeneration/Destination

Yol şablonundaki her yol parametresinin değeri, değerleri ve ortam değerleriyle eşleşen adlarla değiştirilir. Değeri olmayan bir yol parametresi şu şekilde olabilir:

• Varsa varsayılan bir değer kullanın.
• İsteğe bağlıysa atlanır. Örneğin, id rota şablonundan {controller}/{action}/{id?}.

Gerekli bir yol parametresine karşılık gelen bir değer yoksa URL oluşturma işlemi başarısız olur. URL oluşturma bir yol için başarısız olursa, tüm yollar denenene veya eşleşme bulunana kadar sonraki yol denener.

Yukarıdaki örnek, Url.Action geleneksel yönlendirmeyi varsayar. URL oluşturma, öznitelik yönlendirmede benzer şekilde çalışır ancak kavramlar farklıdır. Geleneksel yönlendirme ile:

• Yol değerleri, şablonu genişletmek için kullanılır.
• controller ve action için rota değerleri genellikle bu şablonda yer alır. Yönlendirme tarafından eşleşen URL'ler bir kurala bağlı olduğundan bu işe yarar.

Aşağıdaki örnek öznitelik yönlendirmeyi kullanır:

public class UrlGenerationAttrController : Controller
{
    [HttpGet("custom")]
    public IActionResult Source()
    {
        var url = Url.Action("Destination");
        return ControllerContext.MyDisplayRouteInfo("", $" URL = {url}");
    }

    [HttpGet("custom/url/to/destination")]
    public IActionResult Destination()
    {
       return ControllerContext.MyDisplayRouteInfo();
    }
}

Yukarıdaki Source koddaki eylem oluşturur custom/url/to/destination.

LinkGenerator, IUrlHelper alternatif olarak ASP.NET Core 3.0'a eklendi. LinkGenerator benzer ama daha esnek işlevler sunar. IUrlHelper üzerindeki her yöntemin, LinkGenerator üzerinde de karşılık gelen bir yöntem ailesi vardır.

Eylem adına göre URL oluşturma

Url.Action, LinkGenerator.GetPathByAction ve tüm ilgili aşırı yüklemeler, bir denetleyici adı ve eylem adı belirterek hedef uç noktayı oluşturmak üzere tasarlanmıştır.

Url.Action kullandığınızda, çalışma zamanı controller ve action için geçerli rota değerlerini sağlar:

• controller ile action değerleri hem ortam değerlerinin hem de değerlerin bir parçasıdır. Url.Action yöntemi her zaman action ve controller'nin geçerli değerlerini kullanır ve mevcut eyleme yönlendiren bir URL yolu oluşturur.

Yönlendirme, bir URL oluşturulurken sağlanmayan bilgileri doldurmak için ortam değerlerindeki değerleri kullanmayı dener. {a}/{b}/{c}/{d} gibi, { a = Alice, b = Bob, c = Carol, d = David } ortam değerlerine sahip bir yol düşünün:

• Yönlendirme, ek değer içermeyen bir URL oluşturmak için yeterli bilgiye sahiptir.
• Tüm yol parametrelerinin bir değeri olduğundan yönlendirme yeterli bilgiye sahiptir.

Değer { d = Donovan } eklenirse:

• Değer { d = David } yok sayılır.
• Oluşturulan URL yolu şeklindedir Alice/Bob/Carol/Donovan.

Uyarı: URL yolları hiyerarşiktir. Yukarıdaki örnekte, değer { c = Cheryl } eklenirse:

• Her iki değer { c = Carol, d = David } de yok sayılır.
• Artık için d bir değer yoktur ve URL oluşturma işlemi başarısız olur.
• Bir URL oluşturmak için c ve d için istenen değerleri belirtmeniz gerekir.

Bu sorunla varsayılan yolla {controller}/{action}/{id?} karşılaşmayı bekleyebilirsiniz. Her zaman bir Url.Action ve controller değerini açıkça belirttiği için action bu sorun pratikte nadir görülür.

Url.Action'ın birkaç aşırı yüklemesi, controller ve action dışındaki rota parametreleri için değerler sağlamak üzere bir rota değerleri nesnesi alır. Yol değerleri nesnesi ile idsık sık kullanılır. Örneğin, Url.Action("Buy", "Products", new { id = 17 }). Yol değerleri nesnesi:

• Kurala göre genellikle anonim türde bir nesnedir.
• IDictionary<> veya POCO olabilir).

Yol parametreleriyle eşleşmeyen ek yol değerleri sorgu dizesine gider.

public IActionResult Index()
{
    var url = Url.Action("Buy", "Products", new { id = 17, color = "red" });
    return Content(url!);
}

Yukarıdaki kod, /Products/Buy/17?color=red oluşturur.

Aşağıdaki kod mutlak bir URL oluşturur:

public IActionResult Index2()
{
    var url = Url.Action("Buy", "Products", new { id = 17 }, protocol: Request.Scheme);
    // Returns https://localhost:5001/Products/Buy/17
    return Content(url!);
}

Mutlak URL oluşturmak için aşağıdaki seçeneklerden birini kullanın:

• protocol kabul eden bir aşırı yükleme. Örneğin, önceki kod.
• Varsayılan olarak mutlak URI'ler oluşturan LinkGenerator.GetUriByAction.

Rotaya göre URL'ler oluşturma

Yukarıdaki kod, denetleyiciyi ve eylem adını geçirerek URL oluşturmayı gösterdi. IUrlHelperayrıca Url.RouteUrl yöntem ailesini de sağlar. Bu yöntemler Url.Action yöntemine benzer, ancak action ve controller öğelerinin geçerli değerlerini rota değerlerine kopyalamaz. En yaygın kullanım Url.RouteUrl:

• URL'yi oluşturmak için bir yol adı belirtir.
• Genellikle bir denetleyici veya eylem adı belirtmez.

public class UrlGeneration2Controller : Controller
{
    [HttpGet("")]
    public IActionResult Source()
    {
        var url = Url.RouteUrl("Destination_Route");
        return ControllerContext.MyDisplayRouteInfo("", $" URL = {url}");
    }

    [HttpGet("custom/url/to/destination2", Name = "Destination_Route")]
    public IActionResult Destination()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

Aşağıdaki Razor dosyası, Destination_Route için bir HTML bağlantısı oluşturur:

<h1>Test Links</h1>

<ul>
    <li><a href="@Url.RouteUrl("Destination_Route")">Test Destination_Route</a></li>
</ul>

HTML ve Razor içinde URL'ler oluşturma

IHtmlHelper, sırasıyla HtmlHelper ve öğelerini oluşturmak için Html.BeginForm ve <form><a> yöntemlerini sunar. Bu yöntemler url oluşturmak için Url.Action yöntemini kullanır ve benzer bağımsız değişkenleri kabul eder. Url.RouteUrl için HtmlHelper tamamlayıcıları, benzer işlevlere sahip olan Html.BeginRouteForm ve Html.RouteLink’tür.

TagHelpers, URL'leri form TagHelper ve <a> TagHelper aracılığıyla oluşturur. Bunların her ikisi de uygulamalarında IUrlHelper kullanır. Daha fazla bilgi için bkz. Formlarda Etiket Yardımcıları.

Görünümlerin içinde, önceki yöntemlerin kapsamadığı özel URL oluşturma işlemleri için IUrlHelper öğesine Url özelliği aracılığıyla erişilebilir.

Eylem Sonuçlarında URL oluşturma

Yukarıdaki örneklerde denetleyicide nasıl kullanılacağı IUrlHelper gösterilmektedir. Denetleyicideki en yaygın kullanım, eylem sonucunun bir parçası olarak BIR URL oluşturmaktır.

ControllerBase ve Controller temel sınıfları, başka bir eyleme başvuran eylem sonuçları için kolaylık yöntemleri sağlar. Tipik kullanımlardan biri, kullanıcı girişini kabul ettikten sonra yeniden yönlendirmektir:

[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Edit(int id, Customer customer)
{
    if (ModelState.IsValid)
    {
        // Update DB with new details.
        ViewData["Message"] = $"Successful edit of customer {id}";
        return RedirectToAction("Index");
    }
    return View(customer);
}

RedirectToAction ve CreatedAtAction gibi eylem sonuçları fabrika yöntemleri, IUrlHelper üzerindeki yöntemlere benzer bir düzen izler.

Ayrılmış geleneksel yollar için özel durum

Geleneksel yönlendirme , ayrılmış geleneksel yol olarak adlandırılan özel bir yol tanımı türü kullanabilir. Aşağıdaki örnekte adlı blog yol ayrılmış bir geleneksel yoldur:

app.MapControllerRoute(name: "blog",
                pattern: "blog/{*article}",
                defaults: new { controller = "Blog", action = "Article" });
app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

Önceki yol tanımları kullanıldığında, Url.Action("Index", "Home"), / yolunu kullanarak default URL yolunu oluşturur; peki neden? { controller = Home, action = Index } kullanarak bir URL oluşturmak için blog yol değerlerinin yeterli olduğunu tahmin edebilirsiniz ve sonucun /blog?action=Index&controller=Home olacağını düşünebilirsiniz.

Adanmış geleneksel rotalar, URL oluşturma sırasında rotanın çok greedy olmasını önleyen, karşılık gelen bir rota parametresi bulunmayan varsayılan değerlerin özel bir davranışına dayanır. Bu durumda varsayılan değerler şeklindedir { controller = Blog, action = Article }ve controlleraction yol parametresi olarak gösterilmez. Yönlendirme URL oluşturmayı gerçekleştirirken, sağlanan değerlerin varsayılan değerlerle eşleşmesi gerekir. değerleri blog eşleşmediğinden { controller = Home, action = Index }kullanarak { controller = Blog, action = Article } URL oluşturma işlemi başarısız oluyor. Yönlendirme ardından default öğesini denemeye geri döner ve bu başarılı olur.

Areas

Alanlar , ilgili işlevleri ayrı bir grup halinde düzenlemek için kullanılan bir MVC özelliğidir:

• Denetleyici eylemleri için yönlendirme ad alanı.
• Görünümler için klasör yapısı.

Alanların kullanılması, bir uygulamanın farklı alanlara sahip olduğu sürece aynı ada sahip birden çok denetleyiciye sahip olmasını sağlar. Alanların kullanılması, yönlendirme amacıyla area ve controller öğelerine action biçiminde başka bir rota parametresi ekleyerek bir hiyerarşi oluşturur. Bu bölümde yönlendirmenin alanlarla nasıl etkileşime geçtiği açıklanır. Görünümlerle alanların nasıl kullanıldığı hakkında ayrıntılı bilgi için Alanlar bölümüne bakın.

Aşağıdaki örnek, MVC'yi varsayılan geleneksel rotayı ve area adlı bir area için Blog rotasını kullanacak şekilde yapılandırır:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{    
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapAreaControllerRoute("blog_route", "Blog",
        "Manage/{controller}/{action}/{id?}");
app.MapControllerRoute("default_route", "{controller}/{action}/{id?}");

app.Run();

Yukarıdaki kodda, MapAreaControllerRoute oluşturmak için "blog_route" çağrılır. İkinci parametre olan "Blog", alan adıdır.

gibi /Manage/Users/AddUser"blog_route" bir URL yolu eşleştirildiğinde yol, yol değerlerini { area = Blog, controller = Users, action = AddUser }oluşturur. area yol değeri, area için varsayılan değerden gelir. tarafından MapAreaControllerRoute oluşturulan yol aşağıdaki koda eşdeğerdir:

app.MapControllerRoute("blog_route", "Manage/{controller}/{action}/{id?}",
        defaults: new { area = "Blog" }, constraints: new { area = "Blog" });
app.MapControllerRoute("default_route", "{controller}/{action}/{id?}");

MapAreaControllerRoute, sağlanan alan adını, bu örnekte area, kullanarak Blog için hem varsayılan değer hem de kısıtlama içeren bir rota oluşturur. Varsayılan değer, yolun her zaman { area = Blog, ... } üretmesini sağlar ve kısıtlama ise URL oluşturma için { area = Blog, ... } değerini gerektirir.

Geleneksel yönlendirme, siparişe bağlıdır. Genel olarak, alan içeren rotaları, alan içermeyen rotalardan daha spesifik oldukları için önce yerleştirin.

Yukarıdaki örneği kullanarak yol değerleri aşağıdaki eylemle eşleşmektedir { area = Blog, controller = Users, action = AddUser } :

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace1
{
    [Area("Blog")]
    public class UsersController : Controller
    {
        // GET /manage/users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }        
    }
}

[Alan] özniteliği, bir alanın parçası olarak denetleyiciyi gösteren özelliktir. Bu denetleyici Blog bölgesinde. [Area] özniteliğine sahip olmayan denetleyiciler hiçbir alanın üyesi değildir ve yönlendirme tarafından area rota değeri sağlandığında eşleşmezler. Aşağıdaki örnekte, yalnızca listelenen ilk denetleyici yol değerleriyle { area = Blog, controller = Users, action = AddUser }eşleşebilir.

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace1
{
    [Area("Blog")]
    public class UsersController : Controller
    {
        // GET /manage/users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }        
    }
}

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace2
{
    // Matches { area = Zebra, controller = Users, action = AddUser }
    [Area("Zebra")]
    public class UsersController : Controller
    {
        // GET /zebra/users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }        
    }
}

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace3
{
    // Matches { area = string.Empty, controller = Users, action = AddUser }
    // Matches { area = null, controller = Users, action = AddUser }
    // Matches { controller = Users, action = AddUser }
    public class UsersController : Controller
    {
        // GET /users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }
    }
}

Tamlık için, her denetleyicinin ad alanı burada gösterilir. Önceki denetleyiciler aynı ad alanını kullandıysa bir derleyici hatası oluşturulur. Sınıf ad alanlarının MVC'nin yönlendirmesi üzerinde hiçbir etkisi yoktur.

İlk iki denetleyici alanlara aittir ve yalnızca kendilerine karşılık gelen alan adı area rota değeri tarafından sağlandığında eşleşir. Üçüncü denetleyici herhangi bir alanın üyesi değildir ve yalnızca yönlendirme tarafından area için hiçbir değer sağlanmadığında eşleşebilir.

değer yok ile eşleştirme açısından, area değerinin bulunmaması, area değerinin null veya boş dize olmasıyla aynıdır.

Bir alan içinde bir eylem yürütülürken, area için rota değeri, URL oluşturma sırasında yönlendirme tarafından kullanılabilen bir ortam değeri olarak kullanılabilir. Bu, aşağıdaki örnekte gösterildiği gibi, alanların URL oluşturma için varsayılan olarak kalıcı davrandığı anlamına gelir.

app.MapAreaControllerRoute(name: "duck_route",
                                     areaName: "Duck",
                                     pattern: "Manage/{controller}/{action}/{id?}");
app.MapControllerRoute(name: "default",
                             pattern: "Manage/{controller=Home}/{action=Index}/{id?}");

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace4
{
    [Area("Duck")]
    public class UsersController : Controller
    {
        // GET /Manage/users/GenerateURLInArea
        public IActionResult GenerateURLInArea()
        {
            // Uses the 'ambient' value of area.
            var url = Url.Action("Index", "Home");
            // Returns /Manage/Home/Index
            return Content(url);
        }

        // GET /Manage/users/GenerateURLOutsideOfArea
        public IActionResult GenerateURLOutsideOfArea()
        {
            // Uses the empty value for area.
            var url = Url.Action("Index", "Home", new { area = "" });
            // Returns /Manage
            return Content(url);
        }
    }
}

Aşağıdaki kod, /Zebra/Users/AddUser için bir URL oluşturur:

public class HomeController : Controller
{
    public IActionResult About()
    {
        var url = Url.Action("AddUser", "Users", new { Area = "Zebra" });
        return Content($"URL: {url}");
    }

Eylem tanımı

NonAction özniteliğine sahip olanlar dışında bir denetleyicideki genel yöntemler eylemlerdir.

Örnek kod

• MyDisplayRouteInfo, Rick.Docs.Samples.RouteInfo NuGet paketi tarafından sağlanır ve yol bilgilerini görüntüler.
• Örnek kodu görüntüleme veya indirme (indirme)

Tanılama hatalarını ayıklama

Ayrıntılı yönlendirme tanılama çıktısı için Logging:LogLevel:Microsoft'yı Debug olarak ayarlayın. Development ortamında, appsettings.Development.json içinde günlük seviyesini ayarlayın.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Debug",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}