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 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.
    • APİ'lerle birlikte kullanılan öznitelik yönlendirme. Öncelikli olarak API'ler için yönlendirmeyle ilgileniyorsanız API'ler için öznitelik yönlendirme bölümüne atlayın.
  • Gelişmiş yönlendirme ayrıntıları için bkz. Yönlendirme.
• 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 . Tek bir yol, tek yoldur. Denetleyicileri ve görünümleri olan çoğu uygulama, yola benzer bir yol şablonu kullanır. API'ler öznitelik yönlendirme kullanmalıdır.

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

Yol şablonu :

• Gibi bir URL yoluyla eşleşir

• Yolu belirteçleştirerek yol değerlerini ayıklar . Uygulamada belirtilmiş bir denetleyici ve bir eylem varsa, yol değerlerinin ayıklanması bir eşleşme ile 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.

• model, parametreyi ayarlamak için değeri bağlar. Daha fazla bilgi için bkz. Model Bağlama.

• varsayılan olarak tanımlar.

• varsayılan olarak tanımlar.

• içindeki karakteri isteğe bağlı olarak tanımlar .

  • 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 bakınız: Yol Şablonu Başvuru Kılavuzu.

• URL yolu ile eşleşir .

• Yol değerlerini üretir .

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

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

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

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

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

Kolaylık yöntemi :

app.MapDefaultControllerRoute();

Replaces:

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

Important

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

• Özellik yönlendirilmiş denetleyicileri çağır.
• Hem geleneksel olarak yönlendirilen denetleyicileri hem de öznitelik ile yönlendirilen denetleyicileri eşlemek için 'Çağrı' veya 'Ara'yı kullanın.

Uygulamaların genellikle belirli işlevleri çağırmasına gerek yoktur. ve kullanarak eklenen ara yazılımı sarmalayan bir ara yazılım işlem hattı yapılandırıyor. 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 ş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, denetleyici adına eşlenir.
• İkinci segment, eylem adıyla eşleşir.
• Üçüncü segment, isteğe bağlı bir için kullanılır. in bunu isteğe bağlı hale getirir. bir model varlığıyla eşlenir.

Bu yöntemi kullanarak, URL yolu:

• eyleme haritalanır.
• Eşleştirir ve genellikle model parametreyi 17'ye bağlar.

Bu haritalama:

• Yalnızca denetleyiciyi ve eylem adlarını 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 stili eylemleri olan bir uygulama için, denetleyiciler arasında URL'ler için tutarlılık sağlar:

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

Warning

Yol şablonu, rotayı 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 URL'den çıkarıldığında:

• Model bağlaması olarak ayarlar.
• veritabanında eşleşen varlık bulunamadı.

Öznitelik yönlendirmesi, bazı eylemler için kimliği zorunlu kılma ve diğerleri için gerekli kılmama konusunda ayrıntılı denetim sağlar. Kural gereği, belgelerde doğru kullanımda görünme olasılıkları gibi 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 :

• 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.

ve :

• Çağrılma sırasına göre uç noktalara otomatik olarak bir sıra değeri atayın.

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üğü etkinleştirerek yerleşik yönlendirme uygulamalarının, örneğin , istekleri nasıl eşleştirdiğini görebilirsiniz.

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

Birden çok geleneksel rota

ve öğesine daha fazla çağrı ekleyerek birden çok geleneksel yol 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?}");

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 parametre olarak ve içermediğinden:

• Yalnızca varsayılan değerlerine sahip olabilirler.
• Bu rota her zaman aksiyona eşlenir.

, , ve blog yoluyla eşleşen tek URL yollarıdır.

Yukarıdaki örnekte:

• İlk olarak eklediğiniz için, bu rota eşleşmelerde diğer rotadan daha yüksek önceliğe sahiptir.
• URL'nin bir parçası olarak makale adının bulunmasının tipik olduğu Slug stili yönlendirmeye bir örnektir.

Warning

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

• Yol olarak adlandırılan bir kavram tanımlayın. ara yazılım işlem hattına yol eşleştirmesi ekler. Ara 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.
• veya gibi genişletilebilirlik yürütme sırası hakkında garantiler sağlar.

Yönlendirme hakkında başvuru malzemesi için bkz. Yönlendirme.

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. , ve kullanarak yollar eklediğinizde uç noktalar, bu yöntemleri çağırdığınız sıraya göre otomatik olarak bir sipariş değeri alı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. Tümünü kapsayan yol parametrelerine sahip ayrılmış geleneksel bir rota, bir yolu çok açgözlü hale 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
• Yönlendirme verileri .

Bu, MVC denetleyicileri için tipik bir desendir:

• bir ürünü düzenlemek için bir form görüntüler.
• gönderilmiş formu işler.

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

• , istek bir HTTP olduğunda seçilir.
• , HTTP fiili başka bir şey olduğunda seçilir. genellikle ... aracılığıyla çağrılır.

, , isteğin HTTP yöntemine göre seçebilmesi için yönlendirmeye sağlanır. , değerinden daha iyi bir eşleşme sağlar.

gibi özniteliklerin rolünü anlamak önemlidir. Diğer HTTP fiilleri için benzer öznitelikler tanımlanır. Geleneksel yönlendirmede, bir formu gösterme veya gönderme işlemleri iş akışının parçası olduğunda, eylemler genellikle aynı eylem adını kullanır. Örneğin, bkz . İki Düzenleme eylemi yöntemini inceleme.

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

Geleneksel yol adları

Aşağıdaki örneklerdeki dizeler, geleneksel olarak kullanılan yol 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.

API'ler için öznitelik yönlendirme

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.

Öznitelik yönlendirme, eylemleri doğrudan yol şablonlarıyla eşlemek için bir dizi öznitelik kullanır. Aşağıdaki kod bir 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();

Yukarıdaki kodda, öznitelik yönlendirmeli denetleyicileri eşlemek için çağırırsınız.

Aşağıdaki örnekte:

• , varsayılan geleneksel yolun 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);
    }
}

Eylem, belirtilen herhangi bir URL yolu için çalışır: , , veya .

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önlendirmesi ile, belirteç değiştirme kullanılmadığı sürece denetleyici ve aksiyon adları, hangi aksiyonun eşleşeceği konusunda bir 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 ve için belirteç değişimini 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]")]
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, yöntem şablonlarının yol şablonlarına önceden eklenmesi veya bu şablonlara eklenmesi gerekir. Bir eyleme uygulanan ve belirli bir karakterle başlayan veya başlamayan yol ş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 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 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 bu özel parametre adlarını kullanır.

Aşağıdaki anahtar sözcükler bir görünüm veya 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, yalnızca HTTP GET istekleriyle eşleşen belirli bir özniteliği içerir.
• Eylem şablonu içerdiğinden , denetleyicideki şablonun sonuna eklenir. Yöntemin şablonu şeklindedir . Bu nedenle bu eylem yalnızca , , vb. formu için GET istekleriyle eşleşir.

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

• Eylem şablonu içerir . Şablonun bölümü, yol değerlerini tamsayıya dönüştürülebilecek dizelerle kısıtlar . Bir GET isteği gönder:
  • 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);
    }
    

• Eylem şablonda yer alır , ancak tamsayıya dönüştürülebilecek değerlerle kısıtlamaz . için bir GET isteği:
  • Bu rota ile eşleşir.
  • Model bağlaması bir tamsayıya dönüştürmede başarısız oluyor. yönteminin parametresi tamsayıdır.
  • Model bağlaması tamsayıya dönüştürme konusunda başarısız olduğu için 400 Hatalı İstek döndürür.

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

Öznitelik yönlendirme, , ve 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);
    }
}

URL yolunu kullanma:

• EYLEM, HTTP fiili olduğunda çalışır.
• Eylem, belirli bir HTTP fiili olduğunda çalışır.

BIR API oluştururken, eylem tüm HTTP yöntemlerini kabul ettiğinden, eylem yönteminde kullanmanız çok nadirdir. API'nizin neleri desteklediği konusunda kesin olmak için daha özel HTTP fiil özniteliğini kullanın. API'lerin istemcilerinin, hangi yolların ve HTTP metotlarının belirli mantıksal işlemlerle eşlendiğini bilmesi beklenir.

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, 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 :

• gibi URL yolu ile çalıştırılır
• URL yolu ile çalıştırılmıyor.

[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 .

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

Yol adı

Aşağıdaki kod, yolunun adı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.

Yukarıdaki kodu, parametresini isteğe bağlı () olarak tanımlayan geleneksel varsayılan yolla karşıtlık yapın. API'leri tam olarak belirtebilme özelliği, farklı eylemlere izin verme ve 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 eşleşebilir
• URL yolu "." ile eşleşebilir.

Bu eylemlerin her ikisi de özniteliğiyle işaretlendiğinden yalnızca HTTP ile eşleşer.

Bir eyleme uyguladığınız ve belirli koşullarla başlayan (veya başlamayan) 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 :

Attribute	ile birleştirilir	Yol şablonunu tanımlar
[Route("")]	Yes	"Home"
[Route("Index")]	Yes	"Home/Index"
[Route("/")]	No	""
[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, "api/[controller]" gibi bir öznitelik yolu, "[controller]" gibi bir öznitelik yolundan daha belirgindir. Rota 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 yolları, bir özelliği kullanarak bir düzen yapılandırabilir." Sağlanan çerçevenin tüm rota özniteliklerini kapsadığını unutmayın. Rotalar, özelliğin artan sıraya göre sıralanarak işlenir. Varsayılan sıra şeklindedir . Bir rota, düzeni ayarlanmamış olan rotalardan önce çalıştırılırken ayarlanır. Varsayılan yol sıralaması yapıldıktan sonra bir rota ayarlama gerçekleştirilir.

Bağımlı olmaktan kaçının. 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 uygulanmasından daha basittir.

Her ikisinin de yol 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);
    }
}

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 belirsizlik çözülür:

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

Yukarıdaki kodla uç noktayı çalıştırır . Adrese ulaşmak için istekte bulunun. Note:

• Yukarıdaki kod, kötü yönlendirme tasarımı örneğidir. Bu özelliği gösterir.
• özelliği yalnızca belirsizliği giderir. Bu şablon eşleştirilemez. Şablonu kaldırmak daha iyidir.

Sayfalar ile rota sırası hakkında bilgi için bkz . Sayfalar rotası 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 soruna neden olduğunu görmek için günlük kaydını 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 (, ). , ve belirteçleri, 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

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

• Eşleşmeler

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. 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ğer belirteci değiştirme sınırlayıcısı veya ile eşleşiyorsa, ( veya ) karakterini tekrarlayarak bu sınırlayıcıdan kaçış yapı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 değerini uygular ve dönüştürür. Örneğin, özel bir parametre dönüştürücüsü yol değerini şu şekilde 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();
    }
}

, 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();
    }
}

Yukarıdaki yöntem ile eşleşir .

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'ın tanımı için bkz. Slug üzerinde MDN web belgeleri.

Warning

Güvenilmeyen girişi işlemek için kullanırken bir zaman aşımı geçirin. Kötü amaçlı bir kullanıcı Hizmet Reddi saldırısına neden olacak girişler sağlayabilir. 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ı uygular.

Uygulayan birden çok yol özniteliği bir eyleme 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 yol kısıtlaması uygular. Eylem yalnızca gibi URL yollarıyla eşleştirilir. Yol şablonu bölümü , bu segmenti yalnızca tamsayılarla kısıtlar.

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

IRouteTemplateProvider kullanan özel yol öznitelikleri

Tüm rota öznitelikleri bir işlevi 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ıçtaki yol kümesini oluşturmak için uygulanan öznitelikleri kullanır.

Özel yol özniteliklerini tanımlamak için uygulayın . Her 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 yöntem döndürür .

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

Uygulama modeli:

• 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 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 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 :

[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}");
    }
}

yöntemi:

• Denetleyici öznitelik yönlendirildiyse hiçbir şey yapmaz.
• temeli kaldırılmış olarak denetleyiciler şablonunu temel alarak ayarlar.

Bu, 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 şöyledir.
• Önceki denetleyicinin tam adı şeklindedir .
• Denetleyicilerin şablonunu ayarlar.

, 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 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;
}

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 .

Arabirim, MVC ile URL oluşturma için yönlendirme arasındaki altyapının temel öğesidir. Bir örnek, denetleyicilerde, görünümlerde ve görünüm bileşenlerindeki ilgili özellik aracılığıyla erişilebilir.

Aşağıdaki örnekte, arabirim özelliği aracılığıyla başka bir eylemin 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 değeri URL yol dizesidir . Yönlendirme, şu URL yolunu oluşturmak için aşağıdakileri birleştirir:

• Geçerli istekten gelen ve ortam değerleri olarak adlandırılan yol değerleri.
• yol şablonuna geçirilen ve bu değerlerin yerine geçen değerler:

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, rota şablonundan .

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, 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.
• ve için yol değerleri genellikle bu şablonda görünü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 koddaki eylem oluşturur .

LinkGenerator, IUrlHelper alternatif olarak ASP.NET Core 3.0'a eklendi. benzer ama daha esnek işlevler sunar. Üzerindeki her yöntemin de üzerinde 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.

Kullanırken, çalışma zamanı şu anki ve için geçerli rota değerlerini sağlar:

• 'X' ve 'Y' değerleri hem ortam değerlerinin hem de diğer değerlerin bir parçasıdır. yöntemi her zaman geçerli ve değerlerini kullanır ve geçerli 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. Şuna benzer, ortam değerleriyle 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 eklenirse:

• Değer yoksayılır.
• Oluşturulan URL yolu şeklindedir .

Uyarı: URL yolları hiyerarşiktir. Yukarıdaki örnekte, değer eklenirse:

• Her iki değer de yoksayılır.
• Artık için bir değer yoktur ve URL oluşturma işlemi başarısız olur.
• URL oluşturmak için istenen ve değerlerini belirtmeniz gerekir.

Bu sorunla varsayılan rotada karşılaşabileceğinizi bekleyebilirsiniz. Her zaman bir ve değerini açıkça belirttiği için bu sorun pratikte nadir görülür.

Url.Action'ın çeşitli aşırı yüklemeleri, ve dışındaki yol parametreleri için değerler sağlamak üzere bir yol değerleri nesnesi alır. Yol değerleri nesnesi ile sık sık kullanılır. Örneğin, . Yol değerleri nesnesi:

• Kurala göre genellikle anonim türde bir nesnedir.
• Bir nesne 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 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:

• bir parametre kabul eden 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. ayrıca Url.RouteUrl yöntem ailesini de sağlar. Bu yöntemler Url.Action'a benzer, ancak ve geçerli değerlerini yol değerlerine kopyalamaz. en yaygın kullanımı :

• 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 dosya, bir HTML bağlantısının oluşturulmasını sağlar:

<h1>Test Links</h1>

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

HTML'de URL'ler oluşturma ve

, Html.BeginForm ve Html.ActionLink yöntemlerini sırasıyla ve öğelerini oluşturmak için sağlar. Bu yöntemler url oluşturmak için Url.Action yöntemini kullanır ve benzer bağımsız değişkenleri kabul eder. için eşlikçiler ve'dir ve bunlar benzer işlevlere sahiptir.

TagHelpers, TagHelper ve TagHelper aracılığıyla URL'ler oluşturur. Bunların her ikisi de implementasyonları için kullanılır. Daha fazla bilgi için bkz. Formlarda Etiket Yardımcıları.

İç görünümler, özelliği aracılığıyla, önceki yöntemlerin kapsamına alınmayan geçici URL oluşturma işlemleri için kullanılabilir.

Eylem Sonuçlarında URL oluşturma

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

ve 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);
}

Eylem sonuçları fabrika yöntemleri, gibi ve üzerindeki yöntemlerle benzer bir deseni 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ı 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ını kullanarak, yolu kullanarak URL yolunu oluşturur, ancak neden? Belirli bir yöntemi kullanarak yol değerlerinin bir URL oluşturmaya yeterli olduğunu tahmin edebilirsiniz ve sonuç şu olacaktır: .

Özel geleneksel güzergahlar, URL oluşturma sırasında güzergahın aşırı talepkar olmasını önleyen ve ilgili olmayan yol parametrelerine sahip varsayılan değerlerin özel bir davranışına dayanır. Bu durumda varsayılan değerler şunlardır: , ve ne , ne de yönlendirme parametresi olarak görünür. Yönlendirme URL oluşturmayı gerçekleştirirken, sağlanan değerlerin varsayılan değerlerle eşleşmesi gerekir. değerleri eşleşmediğinden kullanarak URL oluşturma işlemi başarısız oluyor. Ardından yönlendirme, başarılı olan öğesini denemek için geri döner.

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ı kullanmak, ve 'ye başka bir yol parametresi ekleyerek yönlendirme amacıyla bir hiyerarşi oluşturur. Bu bölümde yönlendirmenin alanlarla nasıl etkileşime geçtiği açıklanır. Alanların görünümlerle nasıl kullanıldığı hakkında ayrıntılı bilgi için bkz. Alanlar.

Aşağıdaki örnek, MVC'yi varsayılan geleneksel rotayı ve adlandırılmış bir rota 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, bir işlev belirli bir nesneyi oluşturmak için çağrılır. İkinci parametre olan , alan adıdır.

gibi bir URL yolu eşleştirildiğinde yol, yol değerlerini oluşturur. Rota değeri, bir şey için varsayılan bir değerden gelir. tarafından 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?}");

, sağlanan alan adını (bu örnekte) kullanarak için hem varsayılan değer hem de kısıtlama kullanarak bir yol oluşturur. Varsayılan değer, yolun her zaman belirli bir çıktıyı üretmesini ve kısıtlamanın URL oluşturma için belirli bir değeri gerektirmesini sağlar.

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 :

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 kontrolör bu bölgede. Özniteliği olmayan denetleyiciler, hiçbir alanın üyesi değildir ve yol değeri yönlendirme tarafından sağlandığında eşleşmez. Aşağıdaki örnekte, yalnızca listelenen ilk denetleyici yol değerleriyle 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, alanların üyeleridir ve ancak kendi alan adları yol değeri tarafından sağlandığında eşleşir. Üçüncü denetleyici, herhangi bir bölgenin üyesi değildir ve yalnızca yönlendirme tarafından bir değer sağlanmadığında eşleşebilir.

Değer eşleştirme açısından değerin olmaması, değerin null veya boş dize olmasıyla aynıdır.

Alan içinde bir eylem yürütüldüğünde, URL oluşturma için kullanılacak yönlendirme için yol değeri bir ortam değeri olarak kullanılabilir. Bu, aşağıdaki örnekte gösterildiği gibi, varsayılan olarak ALANLARıN URL oluşturma için yapışkan 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 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üle veya indir (nasıl indirileceğini öğren)

Tanılama hatalarını ayıklama

Ayrıntılı yönlendirme tanılama çıktısı için olarak ayarlayın. ortamında, içinde günlük seviyesini ayarlayın.

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