ASP.NET Core MVC 之路由(Routing)
ASP.NET Core MVC 路由是建立在ASP.NET Core 路由的,一項強大的URL對映元件,它可以構建具有理解和搜尋網址的應用程式。這使得我們可以自定義應用程式的URL命名形式,使得它在搜尋引擎優化(SEO)和連結生成中執行良好,而不用關心Web伺服器上的檔案是怎麼組織的。我們可以方便的使用路由模板語法定義路由,路由模板語法支援路由值約束,預設值和可選值。
基於約束的路由允許全域性定義應用支援的URL格式,以及這些格式是怎樣各自在給定的控制器中對映到指定的操作方法(Action)。當接受到一個請求時,路由引擎解析URL並將其匹配至一個定義URL格式,然後呼叫相關的控制器操作方法。
routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}");
特性路由(Attribute Routing) 允許以在控制器和方法使用新增特性的方式指定路由資訊來定義應用程式的路由。這意味著路由定義緊鄰它們所關聯的控制器和方法。
ASP.NET Core MVC 使用路由中介軟體來匹配傳入請求的URL,並將它們對映到操作方法。路由在啟動程式碼或屬性中定義,它描述了網址路徑應如何與操作方法匹配,還用於響應中生成連結併發送。
1.設定路由中介軟體
建立一個ASP.NET Core Web應用程式,在Startup類的Configure方法中有:
app.UseMvc(routes => { routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}"); });
在對UseMvc的呼叫過程中,MapRoute用於建立單個路由,即預設路由。大多數MVC應用程式都使用與預設路由模板類似的路由。
路由模板{controller=Home}/{action=Index}/{id?} 可以匹配類似 Blog/Details/5 的URL路徑,並且提取路由值 {controller=Blog,action=Details,id=5}。MVC將嘗試查詢名為BlogController的控制器,並執行操作方法。
{controller=Home}將Home定義為預設控制器
{action=Index}將Index定義為預設操作
{id?}將id定義為可選
預設路徑引數和可選路徑引數可以不出現在需要匹配的URL路徑中。
使用{controller=Home}/{action=Index}/{id?}模板,可以對以下URL路徑都執行HomeController.Index:
/Home/Index/7
/Home/Index
/Home
/
有個簡單方法 app.UseMvcWithDefaultRoute() 可以替換掉上面的方法。
UseMvc 和 UseMvcWithDefaultRoute 都是將RouteMiddleware的例項新增到中介軟體管道。MVC不直接與中介軟體互動,而是使用路由來處理請求。MVC通過MvcRouteHandler的例項連結到路由。下面的程式碼與UseMvc類似:
var route = new RouteBuilder(app); //新增連線到MVC,通過呼叫MapRoute來回調 route.DefaultHandler = new MvcRouteHandler(...); //執行回撥以註冊路由 route.MapRoute("default", "{controller=Home}/{action=Index}/{id?}"); //建立路由集合並新增至中介軟體 app.UseRouter(route.Build());
UseMvc 不直接定義任何路由,它為屬性路由的路由集合新增一個佔位符。過載UseMvc 使得我們可以新增自己的路由,並且還支援屬性路由。UseMvc 及其所有變體為屬性路由添加了佔位符,這使得屬性路由始終可用。UseMvcWithDefaultRoute定義預設路由並且支援屬性路由。
2.常規路由
routes.MapRoute(name: "default",template: "{controller=Home}/{action=Index}/{id?}"); 這是一個常規路由,因為它建立了一個約定的URL路徑:
第一路徑段對映到控制器名稱
第二路徑對映到操作名稱
第三區段是可選id,用於對映到模型實體
使用default路由,URL 路徑 /Blog/Index 將對映到BlogController.Index 操作。該對映是基於控制器和操作名稱,而不是基於名稱空間,原始檔位置等。
使用常規路由的預設路由可以快速構建應用程式,而無需定義每一個操作的路由。對於CRUD 操作風格的應用程式,整個控制器的URL具有一致性。
3.多路由
可以在UseMvc 裡面通過新增MapRoute 來新增多個路由。這樣可以定義多個約定,或新增專用於特定操作的常規路由:
app.UseMvc(routes => { routes.MapRoute("blog", "blog/{*article}", defaults: new { Controller = "Blog", Action = "Index" }); routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}"); });
這裡的blog 路由是專用常規路由,這意味著它不採用常規路由系統,而是專用於一個特定地的動作。這個路由始終對映到BlogController.Index。
路由集合中的路由是有序的,並且會按照它們被新增的順序進行處理。
1.回退
作為請求處理的一部分,MVC將驗證路由值是否可以用來查詢應用程式中的控制器和操作。如果路由值不匹配操作,那麼該路由被認為是不匹配的,將嘗試下一個路由。這一過程稱為回退,因為常規路由有重疊的情況。
2.行動歧義
當兩個一致的操作通過路由時,MVC必須消除歧義,選擇最佳操作,否則會丟擲異常。例如:
public class BlogController : Controller { public ActionResult Edit(int id) { return View(); } [HttpPost] public ActionResult Edit(int id, IFormCollection collection) { try { // TODO: Add update logic here return RedirectToAction(nameof(Index)); } catch { return View(); } } }
URL /Blog/Edit/7 可以匹配這兩個操作,這是MVC控制器的典型模式,其中Edit(int)用於顯示編輯的表單,Edit(int,IFormCollection)用於 處理已提交的表單。為了達到這個目的,MVC需要在HTTP POST時選擇Edit(int,IFormCollection),在其他HTTP動詞時選擇Edit(int)。
HttpPostAttribute 是IActionConstraint 的一個實現,它只允許在HTTP動詞為POST時選擇動作。IActionConstraint的存在使得Edit(int,IFormCollection)比Edit(int)更好匹配。
如果有多個路由匹配,並且MVC無法找到一個最佳路由,則會丟擲AmbiguousActionException異常。
3.路由名稱
上面的例子中"blog"和"default"字串是路由名稱,路由名稱為路由提供了一個邏輯名稱,以便命名的路由可用於生成URL。在應用程式範圍內路由必須名稱必須是唯一的。
路由名稱對URL匹配或請求的處理沒有影響,僅用於URL生成。
4.路由特性
特性路由使用一組特性直接將操作對映到路由模板。下面在Configure中呼叫 app.UseMvc(); 沒有傳遞路由。
public class HomeController : Controller { [Route("")] [Route("Home")] [Route("Home/Index")] public IActionResult Index() { return View(); } [Route("Home/About")] public IActionResult About() { ViewData["Message"] = "Your application description page."; return View(); } }
HomeController.Index操作將會對 /,/Home 或者/Home/Index 任一URL訪問執行。
特性路由需要有更多的輸入來指定一個路由,而常規路由處理路由時更加簡潔。然而,特性路由允許精準控制每個操作的路由模板。
上面的模板中沒有定義針對 action,area ,controller的路由引數。實際上,這些引數不允許出現在特性路由中,因為路由模板已經關聯了一個操作,解析URL中的操作名是沒有意義的。
特性路由也可以使用HTTP[Verb]特性,如HTTPPost:
[HttpGet("/Blog")] public ActionResult Index() { return View(); }
由於特性路由適用於特定操作,因此很容易使引數作為模板定義中必須的一部分。下面的例子,id是URL中必須的一部分:
[HttpGet("Blog/Edit/{id}")] public ActionResult Edit(int id) { return View(); }
常規的預設路由定義id引數作為可選項({id?}),而特性路由的是必須引數,這種可以精準指定,比如包/Blog/Get 和 /Blog/Get/{id} 分配到不同的操作。
5.組合路由
為了減少特性路由的重複部分,控制器上的路由特性會和各個操作上的路由特性進行結合。任何定義在控制器上的路由模板都會作為操作路由模板的字首。
[Route("blog")] public class BlogController : Controller { [HttpGet] public ActionResult GetAll() { return View(); } [HttpGet("{id}")] public ActionResult GetById(int id) { return View(); } }
/blog 匹配GetAll方法, /blog/1 匹配 GetById方法。
注意,如果操作上路由模板以 / 開頭時不會結合控制器上的路由模板。
6.特性路由的順序
常規路由會根據定義順序來執行,與之相比,特性路由會構建一個樹形結構,同時匹配所有路由。這種看起來像路由條目被放置在一個理想的順序中,最具體的路由會在一般的路由之前執行。比如,路由blog/Edit/4 比 blog/{*article} 更加具體。
特性路由使用所有框架提供的路由特有的Order屬性來配置順序,並根據Order屬性升序處理路由。預設是0,設定為-1時會在沒有設定的路由之前執行。
7.路由模板中的標記替換( [controller] , [action] , [area])
為了方便,特性路由支援標記替換,即通過在在方括號中封閉一個標記([, ])來替換對應的名稱。標記[action],[area],[controller]會被替換成操作所對應的操作名,區域名,控制器名。
[Route("[controller]/[action]")] public class BlogController : Controller { [HttpGet]//匹配Blog/GetAll public ActionResult GetAll() { return View(); } }
標記替換髮生在構建特性路由的最後一步。與上面結果相同的寫法:
public class BlogController : Controller { [HttpGet("[controller]/[action]")]//匹配Blog/GetAll public ActionResult GetAll() { return View(); } }
特性路由也可以與繼承相結合,即繼承父類的路由標記。
特性路由支援單個操作定義路由。如果用IActionConstarint實現的多個路由特性定義在一個操作上時,每個操作約束與特性定義的路由相結合:
[Route("Store")] [Route("[controller]")] public class BlogController : Controller { [HttpGet("GetAll")]//匹配 Get Blog/GetAll和 Store/GetAll [HttpPost("Set")]//匹配 Post Blog/Set和 Store/Set public ActionResult GetAll() { return View(); } }
雖然使用多個路由到一個操作看起來很強大,但最好還是保持URL的空間簡單和定義明確。使用多個路由到操作上僅僅在特殊需要的時候,比如支援多個客戶端。
8.使用IRouteTemplateProvider自定義路由特性
所有框架提供的路由特性([Route(...) ] ,[HttpGet(...)]等)都實現了 IRouteTemplateProvider 介面。當程式啟動時,MVC查詢控制器類和操作方法上都實現 IRouteTemplateProvider 介面的特性來構建儲時路由集合。
可以通過實現 IRouteTemplateProvider 來定義自己的路由特性。每個 IRouteTemplateProvider 都允許定義使用自定義路由模板,順序以及名稱的單一路由:
public class MyApiControllerAttribute:Attribute, IRouteTemplateProvider { public string Template => "api/[controller]"; public int? Order { get; set; } public string Name { get; set; } }
當 [MyApiController] 特性被應用時,會自動設定Template 為 api/[controller] 。
9.使用應用程式模型來自定義特性路由
應用程式模型時啟動時建立的物件模型,其中包含MVC用於路由和執行操作的所有元資料。應用程式模型包括從路由特性收集的所有資料(通過 IRouteTemplateProvider)。我們可以編寫約定以在啟動時修改應用程式模型為自定義路由行為。
public class NamespaceRoutingConvention: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; } // 使用名稱空間和控制器來推斷控制器的路由 // // Example: // // controller.ControllerTypeInfo -> "My.Application.Admin.UsersController" // baseNamespace -> "My.Application" // // template => "Admin/[controller]" // // 這使得你的路由大致與你的專案結構一致 // var namespc = controller.ControllerType.Namespace; var template = new StringBuilder(); template.Append(namespc,_baseNamespace.Length+1,namespc.Length- _baseNamespace.Length-1); template.Replace('.','/'); template.Append("/[controller]"); foreach (var selector in controller.Selectors) { selector.AttributeRouteModel = new AttributeRouteModel() { Template = template.ToString() }; } } }
這部分怎麼使用,個人還是不是很清楚,這裡只是記錄了官方文件,有哪位知道可以告訴以下小弟。
10.URL生成
MVC應用程式可以使用路由URL的生成特性來生成URL連結到操作。生成URL可以消除硬編碼URL,使程式碼更加健壯和易維護。IUrlHelper 介面是MVC與生成URL路由之間基礎設施的基本塊。可以通過控制器,檢視以及檢視元件中的URL屬性找到一個可用的IUrlHelper例項:
public class HomeController : Controller { public IActionResult Index() { //生成/Home/Contact var url = Url.Action("Contact"); return View(); } public IActionResult Contact() { ViewData["Message"] = "Your application description page."; return View(); } }
這個URL路徑是由路由值與當前請求相結合而成的路由建立,並將值傳遞給Url.Action,替換路由模板中對應的值。
上面Url.Action(的例子是常規路由,但是URL的生成工作與特性路由類似,儘管概念不同。在常規路由中,路由值被用來擴充套件模板,並且關於controller和action的路由值通常出現在那個模板,因為路由匹配的URL堅持了一個約定。在特性路由中,關於controller和action的路由值不允許出現在模板中--它們用來查詢應該使用哪個模板,例如:
//修改Configure public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseMvc(); } public class HomeController : Controller { [HttpGet("/")] public IActionResult Index() { //生成/Home/To/About var url = Url.Action("About"); return View(); } [HttpGet("Home/To/About")] public IActionResult About() { ViewData["Message"] = "Your application description page."; return View(); } }
MVC構建了一個所有特性路由操作的查詢表,並且會匹配controller和action值來選擇路由模板用於生成URL。
11.通過操作名生成URL
Url.Action(this IUrlHelper helper, string action) 以及所有相關的過載都是基於指定控制器名稱和操作名來指定要連結的內容。
當使用Url.Action時,controller 和 action 的當前路由值是指定的 -- controller 和 action 的值同時是環境值和值的一部分。Url.Action 方法總是使用 controller 和 action 的當前值,並且生成路由到當前操作的URL路徑。
路由嘗試使用環境值中的值來填充資訊,同時我們也可以指定路由引數:
public class HomeController : Controller { public IActionResult Index() { //生成/Blog/Edit/1 var url = Url.Action("Edit", "Blog",new { id=1}); //生成/Blog/Edit/1?color=red var url1 = Url.Action("Edit", "Blog", new { id = 1 ,color="red"}); return View(); } }
如果像建立一個絕對URL,可以使用一個接受protocol的過載: Url.Action("Edit", "Blog",new { id=1},protocol:Request.Scheme);
12.通過路由名生成URL
IUrlHelper也提供了 Url.RouteUrl 的系列方法,最常見的是指定一個路由名來使用具體的路由生成URL,通常沒有指定控制器名或操作名:
public class HomeController : Controller { public IActionResult Index() { //生成customer/to/url var url = Url.RouteUrl("AboutRoute"); return View(); } [HttpGet("customer/to/url",Name = "AboutRoute")] public IActionResult About() { ViewData["Message"] = "Your application description page."; return View(); } }
在HTML 中生成的URLHtmlHelper,提供了 HtmlHelper 方法 Html.BeginForm 和 Html.ActionLink 來分別生成<form>和<a>元素。這些方法使用Url.Action方法來生成一個URL,並且它們接受類似的引數。Url.RouteLink ,它們有類似的功能。TagHelper通過form和<a> TagHelper生成URL。這些都使用了IUrlHelper 作為它們的實現。在內部檢視中,IUrlHelper 通過Url 屬性生成任何不包含上述的特定URL。
13.在操作結果中生成URL
在控制器中常見的一個用法是生成一個URL作為操作結果的一部分。Controller和ControllerBase 基類為引用其他操作的操作結果提供了簡單方法。一個典型的方法:
public class HomeController : Controller { public IActionResult Index() { //生成customer/to/url var url = Url.RouteUrl("AboutRoute"); return Redirect(url); //或者 //return RedirectToAction("Contact"); } [HttpGet("customer/to/url",Name = "AboutRoute")] public IActionResult About() { ViewData["Message"] = "Your application description page."; return View(); } public IActionResult Contact() { ViewData["Message"] = "Your contact page."; return View(); } }
RedirectToAction方法有多個過載可以使用。
14.專用常規路由的特殊情況
有一種特殊的路由被稱為專用常規路由,下面被命名為blog的路由就是:
app.UseMvc(routes => { routes.MapRoute("blog", "blog/{*article}", defaults: new { Controller = "Blog", Action = "Index" }); routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}"); });
Url.Action("Index", "Home") 會使用預設路由生成URL。
專用常規路由是依靠預設路由的一個特殊行為,沒有相應的路由引數,以防止路由生成URL“太貪婪”。當路由執行URL生成時,提供的值必須與預設值匹配:否則使用blog的URL生成失敗,因為值 {controller=Home,action=Index}不匹配{controller=Blog,action=Index}。然後路由回退嘗試default,併成功。
15.區域
Areas 是一種MVC功能,用來將相關功能組織為一個組,作為單獨的路由名稱空間(用於控制器操作)和資料夾結構(用於檢視)。使用區域允許應用程式擁有多個相同名稱的控制器——只要它們具有不同的區域。使用區域通過向控制器和操作新增另一個路由引數,區域可建立用於路由目的的層次結構。
使用預設常規路由配置MVC,命名一個OMS區域的路由:
app.UseMvc(routes => { routes.MapAreaRoute("oms", "OMS", "OManage/{controller}/{action}/{id?}", defaults: new { Controller = "Order", Action = "Index" }); routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}"); });
namespace Blog.Areas.OMS.Controllers { [Area("OMS")] public class OrderController : Controller { // GET: Order public ActionResult Index() { return View(); } }
當URL為 /OManage/Order/Edit 時,會匹配路由值 {area = OMS,controller = Order , action = Edit}。area路由值是通過area預設值產生的。使用MapRoute方法也可以實現:
routes.MapRoute("oms", "OManage/{controller}/{action}/{id?}", defaults:new {area="OMS" },constraints:new { area = "OMS" });
MapAreaRoute建立一個路由,同時使用預設路由和area 約束,約束使用提供的區域名 OMS。預設值保證路由總是處理 {area = OMS},約束要求值{area = OMS} 來進行URL生成。
常規路由是順序依賴。一般區域路由放置在前面,因為區域路由更具體。
AreaAttribute表示控制器屬於一個區域的一部分,即這個控制器是在 OMS 區域。控制器不帶[Area] 特性則不屬於任何區域。
當在區域內執行操作時,區域的路由值將作為環境值以用於URL生成,這意味著,在預設情況下,區域對URL生成具有黏性:
namespace Blog.Areas.OMS.Controllers { [Area("OMS")] public class OrderController : Controller { // GET: Order public ActionResult Index() { //生成/OManage/Home/Create var url = Url.Action("Create","Home"); //生成/Home/Create var url1 = Url.Action("Create", "Home",new { area=""}); return View(); } } }
16.IActionConstraint
通常應用程式不需要自定義 IActionConstraint,[HttpGet] 特性以及類似的特性實現 IActionConstraint 介面,以限制方法的執行。
當兩個操作一模一樣,其中一個操作使用 IActionConstraint,總是認為比沒有使用的操作更好,因為它被視為更加具體,並且兩個操作都可以在匹配是被選中。(沒有使用的操作會匹配任何HTTP謂詞)
概念上,IActionConstraint 是過載的一種形式,但不是使用相同名稱的過載,它是匹配相同URL操作的過載。特性路由也使用 IActionConstraint ,並且可以導致不同控制器的操作都被視為候選操作。
實現 IActionConstraint 最簡單的方式是建立一個類派生自 System.Attribute ,並且將它放置到操作和控制器上。MVC會自動發現任何作為特性被應用的 IActionConstraint。你可以使用程式模型來應用約束,可能是最靈活的方法,因為它允許對它們如何被應用進行超程式設計。
一個例子,一個約束選擇一個基於來自路由資料的 country code 操作:
public class CountrySpecificAttribute:Attribute,IActionConstraint { private readonly string _countryCode; public CountrySpecificAttribute(string countryCode) { _countryCode = countryCode; } public int Order { get { return 0; } } public bool Accept(ActionConstraintContext context) { return string.Equals( context.RouteContext.RouteData.Values["country"].ToString(), _countryCode,StringComparison.OrdinalIgnoreCase); } }
Accept 方法返回true,表示當country路由值匹配時操作時匹配的。這個和 RouteValueAttribute 不同,因為它允許回退到一個非特性操作。這個例子展示瞭如果定義一個 en-US 操作,然後國家程式碼是 fr-FR,則會回退到一個更通用的控制器,這個控制器沒有應用 [CountrySpecific(...)] 。
Order屬性和 [HttpGet] 特性中的Order屬性一樣,用來決定執行順序。
&n