A route template is a URL pattern associated with an endpoint. When a request arrives, ASP.NET Core routing compares its URL with registered templates and selects a matching endpoint; endpoint middleware then executes it. A template can identify one fixed URL or accept variable values from many URLs. section 6.2
Build a template from segments:
- Literal segments are fixed. /About/Contact matches /about/contact because matching ignores case, but it does not match /about or /about/contact/email. section 6.3.1
- A name in braces is a required route parameter. /person/{name} matches /person/Andrew and captures Andrew as name. A URL without that segment does not match. section 5.2.1 section 6.3.1
- A default such as {name=all} supplies a value when its segment is absent. A trailing {id?} is optional; if absent, it creates no id route value. An optional parameter without a default must be the last segment. section 6.3.2
One endpoint, several product URLs
With /product/{category}/{name=all}/{id?}, both /product/shoes and /product/shoes/all select the same endpoint with category=shoes and name=all. The URL /product/shoes/formal/3 also supplies id=3. Defaults can make a common URL shorter, but optional and default parameters are best used sparingly so the API remains understandable. section 6.3.2 section 6.5
Listing 5.1 A minimal API that uses a value from the URL
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
WebApplication app = builder.Build();
var people = new List<Person> #1
{ #1
new("Tom", "Hanks"), #1
new("Denzel", "Washington"), #1
new("Leondardo", "DiCaprio"), #1
new("Al", "Pacino"), #1
new("Morgan", "Freeman"), #1
}; #1
app.MapGet("/person/{name}", (string name) => #2
people.Where(p => p.FirstName.StartsWith(name))); #3
app.Run();
This minimal API registers /person/{name} with MapGet. Requesting /person/Al passes Al to the handler, which filters the people list and returns the matching result as JSON. section 5.2.1
Route parameters can also have constraints that prevent a route from matching when a value is unsuitable; constraints help distinguish similar routes, not validate input. A catch-all parameter captures the remaining URL, including slashes. Think carefully about these choices: routes form an application's public URL surface. section 6.5
Razor Pages use the same routing system but normally generate templates from files: Pages/Products/View.cshtml gets Products/View. An Index.cshtml page gets templates both with and without Index. To customize a page, add a segment with a directive such as @page "{category}/{name}", or start with / to replace its file-based template, as in @page "/checkout". Either customization replaces the default template rather than keeping it as an additional route. section 14.3 section 14.4.2
Controller route attributes can combine a controller prefix with an action template: [Route("api/car")] and [Route("speed/{speed}")] produce api/car/speed/{speed}. Starting the action template with / makes it absolute instead. When generating links, use the routing infrastructure so links can remain correct if an endpoint's template changes. section 20.3.1 section 6.5
