The Request Pipeline
When requests are made to a web application, they need to be processed in some way. A number of considerations need to be taken into account. Where should the request be directed or routed to? Should details of the request be logged? Should the application simply return the content of a file? Should it compress the response? What should happen if an exception is encountered while the request is being processed? Is the person making the request actually allowed to access the resource they have requested? How should cookies or other request-related data be handled?
Each of these processing actions are performed by separate components. The term used to describe these components is Middleware. Together, they form the request pipeline.
Middleware in ASP.NET Core
In previous versions of ASP.NET, the components that affected the request pipeline (HttpModules and HttpHandlers) were all bundled into one library, System.Web.dll, along with everything else you might or might not need to make your web application run.
In ASP.NET Core, you can choose which middleware to register in Program.cs or the Configure method of the Startup class for older versions of ASP.NET Core. The standard template includes the following code:
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
}
app.UseStaticFiles();
app.UseAuthentication();
app.UseMvcWithDefaultRoute();
}
Various components are registered including error handling middleware, middleware for processing requests for static files (images, style sheets, script files, PDFs etc), authentication management middleware (if you enable authentication when creating your project), and the MVC framework. Each component is registered using an extension method on the IApplicationBuilder type.
The order in which the components are registered determines the order in which they are executed. Error handling middleware is registered first so that it is available to all code further along the pipeline where exceptions may be raised.
Middleware can either terminate the pipeline execution and return a response or it can pass control on to the next component. The Static File middleware terminates execution of the pipeline and sends the content of the requested static file in the response. Routing, Authentication and EndPoint middleware are not invoked when static files are requested. Other components pass execution on to the next registered component.
Creating Middleware
Middleware is implemented as a RequestDelegate, a delegate that takes an HttpContext as a parameter and returns a Task:
public delegate Task RequestDelegate(HttpContext context);
Here are two examples of middleware. The first is defined as an inline lambda and simply returns a response. It is passed as a parameter to the IApplicationBuilder.Run() method in Program.cs (the Startup's Configure method in earlier versions):
app.Run(async (context) =>
{
await context.Response.WriteAsync("All done");
});
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.Run(async (context) =>
{
await context.Response.WriteAsync("All done");
});
}
This example terminates the pipeline. No other middleware components are executed. The Run method is used specifically for registering middleware that behaves like this.
The next example terminates the response only when a particular query string value is present. Otherwise is passes control on to the next middleware in the pipeline, represented by the next parameter
app.Use(async (context, next) =>
{
if (context.Request.Query.ContainsKey("stop"))
{
await context.Response.WriteAsync("All done");
}
await next();
});
Middleware that passes control on to the next middleware is registered with the IApplicationBuilder Use method.
Middleware Classes
The recommended pattern for creating middleware is to create a separate class for it, and then to create an extension method on the IApplicationBuilder type to register it. There are two ways to author middleware classes. You can use the convention-based approach or you can implement IMiddleware.
Convention-based Middleware
The following code shows a middleware class built on conventions. This is the approach you are most likely to see because it was the only way to write middleware classes before ASP.NET Core 2.0, and most of the framework middleware is written like this.
ElapsedTimeMiddleware.cs
public class ElapsedTimeMiddleware
{
public ElapsedTimeMiddleware(RequestDelegate next) => _next = next;
public async Task Invoke(HttpContext context, ILogger<ElapsedTimeMiddleware> logger)
{
var sw = new Stopwatch();
sw.Start();
await _next(context);
var isHtml = context.Response.ContentType?.ToLower().Contains("text/html");
if (context.Response.StatusCode == 200 && isHtml.GetValueOrDefault())
{
logger.LogInformation($"{context.Request.Path} executed in {sw.ElapsedMilliseconds}ms");
}
}
}
This middleware measures the time taken to process a request and then logs that information.
The class takes a RequestDelegate as a parameter to its constructor. The RequestDelegate represents the next middleware in the pipeline. Convention-based middleware is expected to implement a method named Invoke or InvokeAsync that takes an HttpContext as the first parameter and returns a Task. This method should include the code for processing the request, optionally short-circuiting the pipeline and returning a response, or passing control on to the next middleware. In this example, the Invoke method takes an HttpContext as a parameter and an ILogger.
Within the middleware, a Stopwatch instance is started. Then the request delegate is invoked, resulting in the rest of the pipeline being executed. The code after this line is executed once all subsequent middleware has executed. If the current request returns HTML, the elapsed time is logged:
The logger is injected via the Invoke method instead of the constructor because convention-based middleware is instantiated once at startup and acts as a singleton. Consequently, any dependencies are also created as singletons. Dependencies injected via the Invoke method are only instantiated whenever the method is called and assume the lifetime that they are registered with.
The extension method used to register the middleware is as follows:
public static class BuilderExtensions
{
public static IApplicationBuilder UseElapsedTimeMiddleware(this IApplicationBuilder app)
{
return app.UseMiddleware<ElapsedTimeMiddleware>();
}
}
This method is called in the Configure method in Startup:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseElapsedTimeMiddleware();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
}
app.UseStaticFiles();
app.UseElapsedTimeMiddleware();
app.UseAuthentication();
app.UseMvcWithDefaultRoute();
}
The ElapsedTime middleware is registered after the StaticFiles middleware, ensuring that requests for static files do not start the stop watch.
IMiddleware
The IMiddleware interface was introduced in ASP.NET Core 2.0. IMiddleware is instantiated by a factory for each request that requires it, which means it is instantiated with a scoped lifetime. This means that it is safe to inject scoped and transient services into its constructor. The other benefit of IMiddleware classes is that they do not rely on conventions to work. They rely on implementing the interface, making them strongly typed. IMiddleware is registered in exactly the same way as a convention-based component. The main differences are the class design, and the fact that the class must also be registered with the service container so that the factory can locate it.
Here is the same ElapsedTime middleware based on IMiddleware:
public class ElapsedTimeMiddleware : IMiddleware
{
private readonly ILogger _logger;
public ElapsedTimeMiddleware(ILogger<ElapsedTimeMiddleware> logger) => _logger = logger;
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
var sw = new Stopwatch();
sw.Start();
await _next(context);
var isHtml = context.Response.ContentType?.ToLower().Contains("text/html");
if (context.Response.StatusCode == 200 && isHtml.GetValueOrDefault())
{
_logger.LogInformation($"{context.Request.Path} executed in {sw.ElapsedMilliseconds}ms");
}
}
}
The IMiddleware interface requires the implementation of one method:
Task InvokeAsync(HttpContext context, RequestDelegate next)
It is a very similar pattern to the convention-based middleware, except that dependencies are injected via the constructor. The extension method for registering this middleware is identical to the previous version, but you must also register this middleware with the DI system:
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
services.AddScoped<ElapsedTimeMiddleware>();
}
