Endpoint routing

Endpoint routing was introduced in ASP.NET Core 2.2 and is now the default mechanism as of 3.0. The main advantage is that it supports many different mechanisms that, although leveraging routing and middleware, are very different—MVC, Razor Pages, gRPC, Blazor, SignalR, and whatnot. You still register the services you want in ConfigureServices and then add the middleware to the pipeline using extension methods in the Configure method. Endpoint routing makes the framework more flexible because it decouples route matching and resolution from endpoint dispatching, which used to be all part of the MVC functionality.

There are three required method calls:

• AddRouting: Where we register the required services and optionally configure some of its options (ConfigureServices)
• UseRouting: Where we actually add the routing middleware (Configure); this matches requests to an endpoint
• UseEndpoints: Where we configure the endpoints to be made available (Configure); this executes the matched endpoint

Now, on a Razor view (or page), if you want to generate a hyperlink on the fly that points to an addressable resource, regardless of what it is (an action method, a Razor page, or whatever else), you can just use the Url.RouteUrl overloaded method:

<!-- a Razor page -->
<a href="@Url.RouteUrl(new { page = "Admin" })">Admin</a>

<!-- an action method on a controller -->
<a href="@Url.RouteUrl(new { action = "Contact", controller = "Home" })">Contact</a>

If, for any reason, you need to generate a link on a middleware component, you can inject a LinkGenerator class. It exposes discrete methods that allow you to retrieve many different types of URL information:

• Get{Path,Uri}ByAction: Returns the full path (URL) to a controller's action method
• Get{Path,Uri}ByAddress: Returns the full path (URL) from a base path and specified route values
• Get{Path,Uri}ByName: Returns the full path (URL) from an endpoint name and specified route values
• Get{Path,Uri}ByPage: Returns the full path (URL) from a Razor page name
• Get{Path,Uri}ByRouteValues: Returns the full path (URL) from a named endpoint route and route values

The difference between the *Path and *Uri versions is that the former returns absolute paths (for example, /controller/action) and the latter returns protocol-qualified full paths (for example, http://host:8080/controller/action).

If you need to get the current endpoint, there is a new extension method, GetEndpoint over HttpContext, which you can use for just that:

varendpoint=this.HttpContext.GetEndpoint();
vardisplayName=endpoint.DisplayName;
varmetadata=endpoint.Metadata.ToArray();

The endpoint does not offer much, other than DisplayName and the Metadata collection. DisplayName is the fully qualified name of the action method, including the class and the assembly, unless a display name was set, and the Metadata collection contains all of the metadata, including attributes and conventions, that was applied to the current action method.

You can ask for a specific metadata interface using the Get<T> generic method; the metadata-specific interfaces are as follows:

• IDataTokensMetadata: This is used to get access for the data tokens (see the next section for more on this).
• IEndpointNameMetadata: This is used to get the optional endpoint name.
• IHostMetadata: This is used to get host restrictions for the endpoint.
• IHttpMethodMetadata: This is used to get method restrictions for the endpoint.
• IRouteNameMetadata: This is used to get the route name specified when the route table was defined.
• ISuppressLinkGenerationMetadata: If this interface's SuppressLinkGeneration property is set to true, then this endpoint will not be considered when generating links, using the LinkGenerator class.
• ISuppressMatchingMetadata: If this interface's SuppressMatching property is true, then the URL for this endpoint will not be considered for URL matching.

For example, say we want to get the current route name:

var routeName = HttpContext.GetEndpoint().Metadata.Get<IRouteNameMetadata>();

We can add custom metadata and set the display name on an endpoint upon construction like this:

app.UseEndpoints(endpoints=>
{
    endpoints
        .MapControllerRoute
        (
            name: "Default",                        
            pattern: "{controller=Home}/{action=Index}/{id?}",
        )
        .WithDisplayName("Foo")
        .WithMetadata(new MyMetadata1(), new MyMetadata2());
});

This example shows a typical controller route with a display name set (WithDisplayName) and also custom metadata (MyMetadata1 and MyMetadata2); these classes are just for demo purposes.

Having seen how endpoint routing works, let's now see how we can configure the routing table.