1. Background
When I was planning to write an article about Identityserver4, I found that I didn't know much about EndPoint-Endpoint Routing, so I temporarily gave up research and writing about IdentityServer4; that's why this article about EndPoint came out today.
Turn on your computer and use the powerful Google and Baidu search engines to look up relevant information and open the source code of Asp.net core 3.1 for reading as usual. At the same time, I finally have a different understanding of EndPoint in my practice and testing. When I talk about this, I respect the design of the pipeline model in the framework of Asp.net core 3.x more.
Let me start by asking the following questions:
- How does Asp.Net Core implement Controller's Action when accessing a Web application address?
- What is the relationship between EndPoint and regular routing?
- What is the relationship among the three middleware: UseRouting(), UseAuthorization(), UserEndpoints()?
- How can EndPoint Terminator Routing be used to intercept the execution of an Action and log related actions?(Time is limited, share your next article)
2. Read the Source Code to Understand Confusions
Startup Code
Let's first look at the simplified version of the code in Startup, which follows:
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
Program startup phase:
- Step 1: Execute services.AddControllers()
Register Controller's core services into containers
- Step 2: Execute app.UseRouting()
Register the EndpointRoutingMiddleware in the http pipeline
- Step 3: Execute app.UseAuthorization()
Register the AuthorizationMiddleware in the http pipeline
- Step 4: Execute app.UseEndpoints (encpoints=>endpoints.MapControllers())
There are two main roles:
Call endpoints.MapControllers() to convert all Controllers and Action s defined by this assembly into one EndPoint for RouteOptions, the configuration object of the routing Middleware
Register the Endpoint Middleware in the http pipeline
The app.UseRouting() source code is as follows:
public static IApplicationBuilder UseRouting(this IApplicationBuilder builder) { if (builder == null) { throw new ArgumentNullException(nameof(builder)); } VerifyRoutingServicesAreRegistered(builder); var endpointRouteBuilder = new DefaultEndpointRouteBuilder(builder); builder.Properties[EndpointRouteBuilder] = endpointRouteBuilder; return builder.UseMiddleware<EndpointRoutingMiddleware>(endpointRouteBuilder); }
The Endpoint RoutingMiddleware middleware code is as follows:
internal sealed class EndpointRoutingMiddleware { private const string DiagnosticsEndpointMatchedKey = "Microsoft.AspNetCore.Routing.EndpointMatched"; private readonly MatcherFactory _matcherFactory; private readonly ILogger _logger; private readonly EndpointDataSource _endpointDataSource; private readonly DiagnosticListener _diagnosticListener; private readonly RequestDelegate _next; private Task<Matcher> _initializationTask; public EndpointRoutingMiddleware( MatcherFactory matcherFactory, ILogger<EndpointRoutingMiddleware> logger, IEndpointRouteBuilder endpointRouteBuilder, DiagnosticListener diagnosticListener, RequestDelegate next) { if (endpointRouteBuilder == null) { throw new ArgumentNullException(nameof(endpointRouteBuilder)); } _matcherFactory = matcherFactory ?? throw new ArgumentNullException(nameof(matcherFactory)); _logger = logger ?? throw new ArgumentNullException(nameof(logger)); _diagnosticListener = diagnosticListener ?? throw new ArgumentNullException(nameof(diagnosticListener)); _next = next ?? throw new ArgumentNullException(nameof(next)); _endpointDataSource = new CompositeEndpointDataSource(endpointRouteBuilder.DataSources); } public Task Invoke(HttpContext httpContext) { // There's already an endpoint, skip maching completely var endpoint = httpContext.GetEndpoint(); if (endpoint != null) { Log.MatchSkipped(_logger, endpoint); return _next(httpContext); } // There's an inherent race condition between waiting for init and accessing the matcher // this is OK because once `_matcher` is initialized, it will not be set to null again. var matcherTask = InitializeAsync(); if (!matcherTask.IsCompletedSuccessfully) { return AwaitMatcher(this, httpContext, matcherTask); } var matchTask = matcherTask.Result.MatchAsync(httpContext); if (!matchTask.IsCompletedSuccessfully) { return AwaitMatch(this, httpContext, matchTask); } return SetRoutingAndContinue(httpContext); // Awaited fallbacks for when the Tasks do not synchronously complete static async Task AwaitMatcher(EndpointRoutingMiddleware middleware, HttpContext httpContext, Task<Matcher> matcherTask) { var matcher = await matcherTask; await matcher.MatchAsync(httpContext); await middleware.SetRoutingAndContinue(httpContext); } static async Task AwaitMatch(EndpointRoutingMiddleware middleware, HttpContext httpContext, Task matchTask) { await matchTask; await middleware.SetRoutingAndContinue(httpContext); } } [MethodImpl(MethodImplOptions.AggressiveInlining)] private Task SetRoutingAndContinue(HttpContext httpContext) { // If there was no mutation of the endpoint then log failure var endpoint = httpContext.GetEndpoint(); if (endpoint == null) { Log.MatchFailure(_logger); } else { // Raise an event if the route matched if (_diagnosticListener.IsEnabled() && _diagnosticListener.IsEnabled(DiagnosticsEndpointMatchedKey)) { // We're just going to send the HttpContext since it has all of the relevant information _diagnosticListener.Write(DiagnosticsEndpointMatchedKey, httpContext); } Log.MatchSuccess(_logger, endpoint); } return _next(httpContext); } // Initialization is async to avoid blocking threads while reflection and things // of that nature take place. // // We've seen cases where startup is very slow if we allow multiple threads to race // while initializing the set of endpoints/routes. Doing CPU intensive work is a // blocking operation if you have a low core count and enough work to do. private Task<Matcher> InitializeAsync() { var initializationTask = _initializationTask; if (initializationTask != null) { return initializationTask; } return InitializeCoreAsync(); } private Task<Matcher> InitializeCoreAsync() { var initialization = new TaskCompletionSource<Matcher>(TaskCreationOptions.RunContinuationsAsynchronously); var initializationTask = Interlocked.CompareExchange(ref _initializationTask, initialization.Task, null); if (initializationTask != null) { // This thread lost the race, join the existing task. return initializationTask; } // This thread won the race, do the initialization. try { var matcher = _matcherFactory.CreateMatcher(_endpointDataSource); // Now replace the initialization task with one created with the default execution context. // This is important because capturing the execution context will leak memory in ASP.NET Core. using (ExecutionContext.SuppressFlow()) { _initializationTask = Task.FromResult(matcher); } // Complete the task, this will unblock any requests that came in while initializing. initialization.SetResult(matcher); return initialization.Task; } catch (Exception ex) { // Allow initialization to occur again. Since DataSources can change, it's possible // for the developer to correct the data causing the failure. _initializationTask = null; // Complete the task, this will throw for any requests that came in while initializing. initialization.SetException(ex); return initialization.Task; } } private static class Log { private static readonly Action<ILogger, string, Exception> _matchSuccess = LoggerMessage.Define<string>( LogLevel.Debug, new EventId(1, "MatchSuccess"), "Request matched endpoint '{EndpointName}'"); private static readonly Action<ILogger, Exception> _matchFailure = LoggerMessage.Define( LogLevel.Debug, new EventId(2, "MatchFailure"), "Request did not match any endpoints"); private static readonly Action<ILogger, string, Exception> _matchingSkipped = LoggerMessage.Define<string>( LogLevel.Debug, new EventId(3, "MatchingSkipped"), "Endpoint '{EndpointName}' already set, skipping route matching."); public static void MatchSuccess(ILogger logger, Endpoint endpoint) { _matchSuccess(logger, endpoint.DisplayName, null); } public static void MatchFailure(ILogger logger) { _matchFailure(logger, null); } public static void MatchSkipped(ILogger logger, Endpoint endpoint) { _matchingSkipped(logger, endpoint.DisplayName, null); } } }
We can see from its source that the Endpoint Routing Middleware first creates a matcher, then calls matcher.MatchAsync(httpContext) to find the Endpoint, and finally verifies that the correct Endpoint has been matched by httpContext.GetEndpoint() and hands in the next middleware to continue execution!
app.UseEndpoints() Source Code
public static IApplicationBuilder UseEndpoints(this IApplicationBuilder builder, Action<IEndpointRouteBuilder> configure) { if (builder == null) { throw new ArgumentNullException(nameof(builder)); } if (configure == null) { throw new ArgumentNullException(nameof(configure)); } VerifyRoutingServicesAreRegistered(builder); VerifyEndpointRoutingMiddlewareIsRegistered(builder, out var endpointRouteBuilder); configure(endpointRouteBuilder); // Yes, this mutates an IOptions. We're registering data sources in a global collection which // can be used for discovery of endpoints or URL generation. // // Each middleware gets its own collection of data sources, and all of those data sources also // get added to a global collection. var routeOptions = builder.ApplicationServices.GetRequiredService<IOptions<RouteOptions>>(); foreach (var dataSource in endpointRouteBuilder.DataSources) { routeOptions.Value.EndpointDataSources.Add(dataSource); } return builder.UseMiddleware<EndpointMiddleware>(); } internal class DefaultEndpointRouteBuilder : IEndpointRouteBuilder { public DefaultEndpointRouteBuilder(IApplicationBuilder applicationBuilder) { ApplicationBuilder = applicationBuilder ?? throw new ArgumentNullException(nameof(applicationBuilder)); DataSources = new List<EndpointDataSource>(); } public IApplicationBuilder ApplicationBuilder { get; } public IApplicationBuilder CreateApplicationBuilder() => ApplicationBuilder.New(); public ICollection<EndpointDataSource> DataSources { get; } public IServiceProvider ServiceProvider => ApplicationBuilder.ApplicationServices; }
The code builds a DefaultEndpointRouteBuilder endpoint routing builder object, which stores the collection data of the Endpoint, stores the collection data of the Endpoint routing in the routeOptions, and registers the Endpoint Middleware in the http pipeline.
The Endpoint object code is as follows:
/// <summary> /// Represents a logical endpoint in an application. /// </summary> public class Endpoint { /// <summary> /// Creates a new instance of <see cref="Endpoint"/>. /// </summary> /// <param name="requestDelegate">The delegate used to process requests for the endpoint.</param> /// <param name="metadata"> /// The endpoint <see cref="EndpointMetadataCollection"/>. May be null. /// </param> /// <param name="displayName"> /// The informational display name of the endpoint. May be null. /// </param> public Endpoint( RequestDelegate requestDelegate, EndpointMetadataCollection metadata, string displayName) { // All are allowed to be null RequestDelegate = requestDelegate; Metadata = metadata ?? EndpointMetadataCollection.Empty; DisplayName = displayName; } /// <summary> /// Gets the informational display name of this endpoint. /// </summary> public string DisplayName { get; } /// <summary> /// Gets the collection of metadata associated with this endpoint. /// </summary> public EndpointMetadataCollection Metadata { get; } /// <summary> /// Gets the delegate used to process requests for the endpoint. /// </summary> public RequestDelegate RequestDelegate { get; } public override string ToString() => DisplayName ?? base.ToString(); }
Two key type attributes in the Endpoint object code are the Endpoint MetadataCollection type and RequestDelegate:
- EndpointMetadataCollection: Stores a collection of elements related to Controller and Action, including Attribute attribute data on Action, etc.
- RequestDelegate: Stores Actions, or delegates, where is the Action method for each Controller
Looking back at the Endpoint Middleware middleware and core code, one of the core codes for Endpoint Middleware is to execute the RequestDelegate delegate for Endpoint, that is, to execute the Action s in Controller.
public Task Invoke(HttpContext httpContext) { var endpoint = httpContext.GetEndpoint(); if (endpoint?.RequestDelegate != null) { if (!_routeOptions.SuppressCheckForUnhandledSecurityMetadata) { if (endpoint.Metadata.GetMetadata<IAuthorizeData>() != null && !httpContext.Items.ContainsKey(AuthorizationMiddlewareInvokedKey)) { ThrowMissingAuthMiddlewareException(endpoint); } if (endpoint.Metadata.GetMetadata<ICorsMetadata>() != null && !httpContext.Items.ContainsKey(CorsMiddlewareInvokedKey)) { ThrowMissingCorsMiddlewareException(endpoint); } } Log.ExecutingEndpoint(_logger, endpoint); try { var requestTask = endpoint.RequestDelegate(httpContext); if (!requestTask.IsCompletedSuccessfully) { return AwaitRequestTask(endpoint, requestTask, _logger); } } catch (Exception exception) { Log.ExecutedEndpoint(_logger, endpoint); return Task.FromException(exception); } Log.ExecutedEndpoint(_logger, endpoint); return Task.CompletedTask; } return _next(httpContext); static async Task AwaitRequestTask(Endpoint endpoint, Task requestTask, ILogger logger) { try { await requestTask; } finally { Log.ExecutedEndpoint(logger, endpoint); } } }
Answer questions:
1. How does Asp.Net Core implement Controller's Action when accessing a Web application address?
Answer: When the program starts, it stores all the Action mappings in the Controller into the set of routeOptions, maps the Action to the RequestDelegate delegate attribute of the Endpoint terminator, and finally executes by adding the Endpoint Middleware via UseEndPoints, where the Endpoint terminator route has already been matched through Routing.
2. What is the relationship between EndPoint and regular routing?
Answer: Ednpoint terminator routing is a delegated route after map conversion of a normal route, which contains all the element information of the routing method, EndpointMetadataCollection and RequestDelegate delegation.
3. What is the relationship among the three middleware: UseRouting (), UseAuthorization(), UseEndpoints()?
Answer: The UseRouting middleware is mainly about routing matching, finding matching endpoints for routes, and the Use Endpoint s middleware is mainly about executing delegation methods for routes matched by the UseRouting middleware.
The UseAuthorization Middleware mainly intercepts the matched routes in the UseRouting Middleware for authorization verification, etc. By executing the next middleware UseEndpoints(), you can see the flow chart below for the specific relationship:
Some parts have been omitted from the above flowchart to highlight the relationship among the three middleware: UseRouting, UseAuthorization, and UseEndpoint.
Finally, we can register other powerful custom middleware between UseRouting() and UseEndpoint() registered Http pipelines to implement our own business logic
If there are any errors above, please actively correct them, thank you for your support!!