RP conventions topic+sample updates (#8523)
Luke Latham
GitHub
parent
190c62af0c
commit
b7ba93461f
|
|
@ -3,7 +3,7 @@ title: Routing to controller actions in ASP.NET Core
|
|||
author: rick-anderson
|
||||
description: Learn how ASP.NET Core MVC uses Routing Middleware to match URLs of incoming requests and map them to actions.
|
||||
ms.author: riande
|
||||
ms.date: 03/14/2017
|
||||
ms.date: 09/17/2018
|
||||
uid: mvc/controllers/routing
|
||||
---
|
||||
# Routing to controller actions in ASP.NET Core
|
||||
|
|
@ -371,6 +371,8 @@ Attribute routes can configure an order, using the `Order` property of all of th
|
|||
> [!TIP]
|
||||
> Avoid depending on `Order`. If your URL-space requires explicit order values to route correctly, then it's likely confusing to clients as well. In general attribute routing will select the correct route with URL matching. If the default order used for URL generation isn't working, using route name as an override is usually simpler than applying the `Order` property.
|
||||
|
||||
Razor Pages routing and MVC controller routing share an implementation. Information on route order in the Razor Pages topics is available at [Razor Pages route and app conventions: Route order](xref:razor-pages/razor-pages-conventions#route-order).
|
||||
|
||||
<a name="routing-token-replacement-templates-ref-label"></a>
|
||||
|
||||
## Token replacement in route templates ([controller], [action], [area])
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ author: guardrex
|
|||
description: Discover how route and app model provider conventions help you control page routing, discovery, and processing.
|
||||
monikerRange: '>= aspnetcore-2.0'
|
||||
ms.author: riande
|
||||
ms.date: 04/12/2018
|
||||
ms.date: 09/17/2018
|
||||
uid: razor-pages/razor-pages-conventions
|
||||
---
|
||||
# Razor Pages route and app conventions in ASP.NET Core
|
||||
|
|
@ -63,6 +63,26 @@ public void ConfigureServices(IServiceCollection services)
|
|||
}
|
||||
```
|
||||
|
||||
## Route order
|
||||
|
||||
Routes specify an <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel.Order*> for processing (route matching).
|
||||
|
||||
| Order | Behavior |
|
||||
| :--------------: | -------- |
|
||||
| -1 | The route is processed before other routes are processed. |
|
||||
| 0 | Order isn't specified (default value). Not assigning `Order` (`Order = null`) defaults the route `Order` to 0 (zero) for processing. |
|
||||
| 1, 2, … n | Specifies the route processing order. |
|
||||
|
||||
Route processing is established by convention:
|
||||
|
||||
* Routes are processed in sequential order (-1, 0, 1, 2, … n).
|
||||
* When routes have the same `Order`, the most specific route is matched first followed by less specific routes.
|
||||
* When routes with the same `Order` and the same number of parameters match a request URL, routes are processed in the order that they're added to the <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.PageConventionCollection>.
|
||||
|
||||
If possible, avoid depending on an established route processing order. Generally, routing selects the correct route with URL matching. If you must set route `Order` properties to route requests correctly, the app's routing scheme is probably confusing to clients and fragile to maintain. Seek to simplify the app's routing scheme. The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. However, you should attempt to avoid the practice of setting route `Order` in production apps.
|
||||
|
||||
Razor Pages routing and MVC controller routing share an implementation. Information on route order in the MVC topics is available at [Routing to controller actions: Ordering attribute routes](xref:mvc/controllers/routing#ordering-attribute-routes).
|
||||
|
||||
## Model conventions
|
||||
|
||||
Add a delegate for [IPageConvention](/dotnet/api/microsoft.aspnetcore.mvc.applicationmodels.ipageconvention) to add [model conventions](xref:mvc/controllers/application-model#conventions) that apply to Razor Pages.
|
||||
|
|
@ -75,8 +95,13 @@ The sample app adds a `{globalTemplate?}` route template to all of the pages in
|
|||
|
||||
[!code-csharp[](razor-pages-conventions/sample/Conventions/GlobalTemplatePageRouteModelConvention.cs?name=snippet1)]
|
||||
|
||||
> [!NOTE]
|
||||
> The `Order` property for the `AttributeRouteModel` is set to `-1`. This ensures that this template is given priority for the first route data value position when a single route value is provided and also that it would have priority over automatically generated Razor Pages routes. For example, the sample adds an `{aboutTemplate?}` route template later in the topic. The `{aboutTemplate?}` template is given an `Order` of `1`. When the About page is requested at `/About/RouteDataValue`, "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = -1`) and not `RouteData.Values["aboutTemplate"]` (`Order = 1`) due to setting the `Order` property.
|
||||
The <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel.Order*> property for the <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel> is set to `1`. This ensures the following route matching behavior in the sample app:
|
||||
|
||||
* A route template for `TheContactPage/{text?}` is added later in the topic. The Contact Page route has a default order of `null` (`Order = 0`), so it matches before the `{globalTemplate?}` route template.
|
||||
* An `{aboutTemplate?}` route template is added later in the topic. The `{aboutTemplate?}` template is given an `Order` of `2`. When the About page is requested at `/About/RouteDataValue`, "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = 1`) and not `RouteData.Values["aboutTemplate"]` (`Order = 2`) due to setting the `Order` property.
|
||||
* An `{otherPagesTemplate?}` route template is added later in the topic. The `{otherPagesTemplate?}` template is given an `Order` of `2`. When any page in the *Pages/OtherPages* folder is requested with a route parameter (for example, `/OtherPages/Page1/RouteDataValue`), "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = 1`) and not `RouteData.Values["otherPagesTemplate"]` (`Order = 2`) due to setting the `Order` property.
|
||||
|
||||
Wherever possible, don't set the `Order`, which results in `Order = 0`. Rely on routing to select the correct route.
|
||||
|
||||
Razor Pages options, such as adding [Conventions](/dotnet/api/microsoft.aspnetcore.mvc.razorpages.razorpagesoptions.conventions), are added when MVC is added to the service collection in `Startup.ConfigureServices`. For an example, see the [sample app](https://github.com/aspnet/Docs/tree/master/aspnetcore/razor-pages/razor-pages-conventions/sample/).
|
||||
|
||||
|
|
@ -145,8 +170,9 @@ The sample app uses `AddFolderRouteModelConvention` to add an `{otherPagesTempla
|
|||
|
||||
[!code-csharp[](razor-pages-conventions/sample/Startup.cs?name=snippet3)]
|
||||
|
||||
> [!NOTE]
|
||||
> The `Order` property for the `AttributeRouteModel` is set to `1`. This ensures that the template for `{globalTemplate?}` (set earlier in the topic) is given priority for the first route data value position when a single route value is provided. If the Page1 page is requested at `/OtherPages/Page1/RouteDataValue`, "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = -1`) and not `RouteData.Values["otherPagesTemplate"]` (`Order = 1`) due to setting the `Order` property.
|
||||
The <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel.Order*> property for the <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel> is set to `2`. This ensures that the template for `{globalTemplate?}` (set earlier in the topic to `1`) is given priority for the first route data value position when a single route value is provided. If a page in the *Pages/OtherPages* folder is requested with a route parameter value (for example, `/OtherPages/Page1/RouteDataValue`), "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = 1`) and not `RouteData.Values["otherPagesTemplate"]` (`Order = 2`) due to setting the `Order` property.
|
||||
|
||||
Wherever possible, don't set the `Order`, which results in `Order = 0`. Rely on routing to select the correct route.
|
||||
|
||||
Request the sample's Page1 page at `localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue` and inspect the result:
|
||||
|
||||
|
|
@ -160,8 +186,9 @@ The sample app uses `AddPageRouteModelConvention` to add an `{aboutTemplate?}` r
|
|||
|
||||
[!code-csharp[](razor-pages-conventions/sample/Startup.cs?name=snippet4)]
|
||||
|
||||
> [!NOTE]
|
||||
> The `Order` property for the `AttributeRouteModel` is set to `1`. This ensures that the template for `{globalTemplate?}` (set earlier in the topic) is given priority for the first route data value position when a single route value is provided. If the About page is requested at `/About/RouteDataValue`, "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = -1`) and not `RouteData.Values["aboutTemplate"]` (`Order = 1`) due to setting the `Order` property.
|
||||
The <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel.Order*> property for the <xref:Microsoft.AspNetCore.Mvc.ApplicationModels.AttributeRouteModel> is set to `2`. This ensures that the template for `{globalTemplate?}` (set earlier in the topic to `1`) is given priority for the first route data value position when a single route value is provided. If the About page is requested with a route parameter value at `/About/RouteDataValue`, "RouteDataValue" is loaded into `RouteData.Values["globalTemplate"]` (`Order = 1`) and not `RouteData.Values["aboutTemplate"]` (`Order = 2`) due to setting the `Order` property.
|
||||
|
||||
Wherever possible, don't set the `Order`, which results in `Order = 0`. Rely on routing to select the correct route.
|
||||
|
||||
Request the sample's About page at `localhost:5000/About/GlobalRouteValue/AboutRouteValue` and inspect the result:
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ namespace ModelProvidersSample.Conventions
|
|||
{
|
||||
AttributeRouteModel = new AttributeRouteModel
|
||||
{
|
||||
Order = -1,
|
||||
Order = 1,
|
||||
Template = AttributeRouteModel.CombineTemplates(
|
||||
selector.AttributeRouteModel.Template,
|
||||
"{globalTemplate?}"),
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ namespace ModelProvidersSample
|
|||
{
|
||||
AttributeRouteModel = new AttributeRouteModel
|
||||
{
|
||||
Order = 1,
|
||||
Order = 2,
|
||||
Template = AttributeRouteModel.CombineTemplates(
|
||||
selector.AttributeRouteModel.Template,
|
||||
"{otherPagesTemplate?}"),
|
||||
|
|
@ -69,7 +69,7 @@ namespace ModelProvidersSample
|
|||
{
|
||||
AttributeRouteModel = new AttributeRouteModel
|
||||
{
|
||||
Order = 1,
|
||||
Order = 2,
|
||||
Template = AttributeRouteModel.CombineTemplates(
|
||||
selector.AttributeRouteModel.Template,
|
||||
"{aboutTemplate?}"),
|
||||
|
|
|
|||
Loading…
Reference in New Issue