Routing in asp.net core razor pages

Suggested Videos
Part 5 - Razor Pages - Creating Reusable Data Access Project | Text | Slides
Part 6 - Registering services in razor pages project | Text | Slides
Part 7 - List razor page | Text | Slides

In this video we will discuss the basics of routing in asp.net core razor pages.

Routing in razor pages


Like MVC, ASP.NET core razor pages also uses a combination of  conventions and configuration to control how routing works. It is important to keep in mind, razor pages also use the same routing infrastructure as MVC under the hood. The difference is in how routes are configured.


In ASP.NET Core MVC, we use either convention-based or attribute routing to match an incoming request URL to a controller action.

In razor pages, the path to the file determines the URL at which the page can be reached. By default, all razor pages live in the Pages directory. 

Default URL mapping in razor pages

For example, consider the following file and folder structure.



You can reach Index.cshtml razor page in the Pages folder, by navigating to https://localhost:1234/Index. https://localhost:1234 is the host and /Index is the URL to get to the Index.cshtml razor page. The root folder (i.e Pages) and the file extension .cshtml are not required in the URL.

Index.cshtml is the default document. So you can reach it using one of the following 2 routes

https://localhost:1234/
https://localhost:1234/Index

Similarly

/Privacy is mapped to Pages/Privacy.cshtml
/Employees/Details is mapped to Pages/Employees/Details.cshtml
The 2 routes /Employees and /Employees/Index are mapped to Pages/Employees/Index.cshtml

AmbiguousMatchException: The request matched multiple endpoints

At this point if we add Employees.cshtml razor page to the Pages folder and navigate to /Employees/Index, the razor page (Pages/Employees/List.cshtml) is served as expected. However, the URL (/Employees) will throw the following exception.

AmbiguousMatchException: The request matched multiple endpoints. Matches:

/Employees
/Employees/Index

Since a single URL is mapped to multiple razor pages, asp.net core does not know which page to serve, so it throws an exception. The simplest way to resolve this error is to rename one of the matching razor pages name. If you do not prefer to change the name of the razor page, you can resolve this error, either by overiding default routes or by using route parameters.

Overriding Default Routes

In razor pages, by default URLs are mapped to physical files on the file system. However, we can override this default behaviour, so there is no relationship with the file name.

For example, to reach Pages/Employees/Index.cshtml, we use one of the following URLs

/Employees (This is throwing an exception as it matches multiple razor pages)
/Employees/Index

You can override this default route using the @page directive as shown below

@page "/EmployeeList"

Once you have this directive in place, you can only use /EmployeeList to reach (Pages/Employees/Index.cshtml). /Employees/Index will result in 404

Notice in the example below, the route does not start with slash (/ or ~/). So this route segment becomes relative and you have to use the URL /Employees/List to reach (Pages/Employees/Index.cshtml)
@page "List"

Razor page route parameters

We can also use route parameters to reslove AmbiguousMatchException. Route parameters are specified using curly braces. 

@page "/Employees/{name}"

You can pass any value for the name parameter. ABC, David, 123 etc. So all the following URLs map to Pages/Employees/Index.cshtml razor page.

/Employees/ABC
/Employees/David
/Employees/123

The URL, /Employees map to /Employees/Index.cshtml razor page.

We can also specify constraints on route parameters. We will discuss route parameters and constraints in detail in our upcoming videos.