ASP.NET Core Endpoint Routing

EndPoint Routing is the new way to implement the Routing in ASP.NET Core. It splits up the old routing middleware into two separate middleware’s and also decouples the MVC from the Routing Middleware. Learn what is Endpoint is and how to register these routing middleware’s using the UseRouting & UseEndpoints methods in the Configure method of the startup class.

The Article Applies to ASP.NET Core 3.0 or later. For Previous Version of the ASP.NET core check the article Routing in ASP.NET Core 2.0

What is Endpoint Routing in ASP.NET Core

The Endpoint Routing is the Process by which ASP.NET Core inspects the incoming HTTP requests and maps them to applications executable Endpoint. We define the Endpoint during the application startup. The Routing Module then matches the incoming URL to an Endpoint and dispatches the request to it.

The Endpoint Routing Module also decouples the route matching functions and endpoint dispatching functions using the two separate middleware’s.

  1. The EndPointRoutingMiddleware resolves the HTTP request to an Endpoint (route matching).
  2. The EndpointMiddleware invokes the Endpoint (endpoint dispatching). 

Before ASP.NET Core 3.0 

Before ASP.NET Core 3.0 the Route resolution & invoking of the Route were part of the MVC Middleware. We defined the routes while configuring the MVC is using the app.UseMvc as shown below

  1. When a new request arrives, the routing middleware parses the incoming URL.
  2. A matching route is searched in the RouteCollection.
  3. If a matching route is found, control is passed to the RouteHandler 
  4. If a matching route is not found, the next middleware is invoked.

What is an Endpoint

An Endpoint is an object that contains everything that you need to execute the incoming Request. The Endpoint object contains the following information

  1. Metadata of the request.
  2. The delegate (Request handler) that ASP.NET core uses to process the request.

We define the Endpoint at the application startup using the UseEndpoints method.

The ASP.NET Core routing is now not tied up only to the MVC Endpoints. You can define an Endpoint, which can also hit a Razor page, SignalR etc.

The following are the the Endpoints that you can configure in ASP.NET Core app.

  1. MVC Controller Action Method
  2. Web API Controller Action Method
  3. Razor page
  4. SignalR
  5. gRPC Services
  6. Blazer on the server
  7. Endpoint defined in an middleware
  8. Delegates and lambdas registered with routing.

How Endpoint Routing Works

The Endpoint Routing has three components

  1. Defining the Endpoints.
  2. Route matching & Constructing an Endpoint (UseRouting).
  3. Endpoint Execution (UseEndpoints).

To understand how it works, Create a new ASP.NET Core application in VS 2019 ( Min Version 16.9.1 ) and .NET 5.0. Choose the Web Application (Model-View-Controller) Template.

Open the startup class.

Configure the Endpoint

We configure the Endpoint in the app.UseEndpoints method.

The following method adds the default MVC Conventional route using the MapControllerRoute method. The following adds the default conventional route to MVC Controllers using a pattern.

To setup an attribute based Routing use the method MapControllers. We use the attribute based Routing to create a route to Rest API (Web API Controller Action Method). You can also use it to create a route to MVC Controller action method.

MapControllerRoute & MapControllers methods hides all the complexities of setting up the Endpoint from us. Both sets up the Endpoint to Controller action methods

You can also create an Endpoint to a custom delegate using MapGet method. MapGet accepts two argument. One is Route Pattern (/ in the example) and a request delegate.

UseRouting

The EndPointRoutingMiddleware resolves the incoming HTTP requests and constructs an Endpoint.

We register it very early in the middleware pipeline using the UseRouting method.

Its purpose is to

  1. Parse the incoming URL
  2. Resolve the URL and construct the Endpoint.
  3. Updates the HTTP Context object with the endpoint using the SetEndpoint method.

The Endpoint objects are immutable and cannot be modified after creation.

The Middleware running after UseRouting can access the endpoint from the HTTP Context and take action. For example, an authorization middleware can query the metadata of the endpoint and apply the correct authorization policy based on that information.

UseEndpoints

The EndpointMiddleware is responsible for execution the Endpoint. We register the it using the UseEndpoints method. It reads the Endpoint, which was selected by the Route Matching middleware and runs the delegate associated with it.

Remember, we also configure the endpoints in the UseEndpoints method

  1. The EndpointMiddleware middleware is terminal Middleware when a match is found
  2. The middleware after UseEndpoints execute only when no match is found.

Endpoint Routing in Action

In the following example, we are using the MapGet to create two custom Endpoints

MapGet is an extension method, on EndpointRouteBuilder and accepts two arguments.

The first argument is route pattern as string. The second argument is a request delegate, which will be executed when the Endpoint is matched.

The Code above defines two Endpoints. One is root URL / and the other one is /hello.

Request delegates in both the Endpoints print Hello World to the response stream. The second delegate uses the the method helloWorld() to do so.

When the app starts, UseRouting registers the Route Matching Middleware EndPointRoutingMiddleware. UseEndpoints method registers the Endpoint execution middleware EndpointMiddleware. UseEndpoints also configures the Endpoints.

When the request arrives to root URL / or to the /hello URL, the Route Matching Middleware will construct the Endpoint and updates the context. The later in the middleware the EndpointMiddleware reads the Endpoint from the context and executes its delegate.

Any request other than the above, will not have any Endpoints, and hence will throw the 404 error. Also note that MapGet maps to HTTP GET requests only. Any other request like POST, PUT etc returns 404 status code.

Reading Endpoints in Middleware

Any Middleware between the UseRouting and UseEndpoints can access the the Endpoint from the context using the GetEndpoint mehod.

In the following code adds a custom middleware after UseRouting. If Endpoint is not null, it extracts the DisplayName, RoutePattern & metdata from the Endpoint and writes it to the response stream.

Set a breakpoint to inspect the properties of the Endpoint.

Inspecting the ASP.NET Core Endpoint

Defining the Endpoints

As shown earlier, we configure the Endpoint in the app.UseEndpoints method.

The ASP.NET Core supports many scenarios in developing apps. They include web apps like MVC, Razor Pages & Blazor. You can also build Web APIs or real time Apps using SignalR. Use gRPC to build Remote Procedure call apps, etc.

The ASP.NET Core provides several extension methods to setup & configure the Endpoints.

You can create endpoint to custom delegates using the map methods like MapGet, MapPost, MapPut, MapDelete, & Map

Use MapRazorPages to adds all the required Endpoints which maps to Razor Pages

Similarly, you can use the MapHub to configure the SignalR endpoint

Use MapGrpcService  to Create Endpoint to a gRPC service.

Routing to Controller Action

MVC & Web API require us to setup Endpoint to each controller action methods. There are two different ways by which we can set up routes.

  1. Convention-based routing
  2. Attribute routing

Convention-based routing

Conventional based routing is typically used with the controllers and views. It creates routes based on a series of conventions. We define it using the endpoints.MapControllerRoute method.

In the above example, the MapControllerRoute creates a single route, which is named as default and the URL Pattern of the route is {controller=Home}/{action=Index}/{id?}

You can read more about Convention based routing in ASP.NET Core

Attribute routing

The attribute routing uses the attributes defined directly on the controller action to define the routes. Attribute routing gives you more control over the URLs in your web application.

To make use of the attribute routing use the MapControllers method.

You can read more about attribute routing in ASP.NET Core

References

Official Documentation on Routing

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top