Imagine walking into a high-security office building. Before you reach your destination on the 10th floor, you have to pass through a series of checkpoints: the front desk verifies your ID, the security scanner checks your bags, and the elevator requires a keycard. If any of these checks fail, your journey stops immediately.
In the world of ASP.NET Core, this journey is the HTTP request, and those checkpoints are what we call Middleware. Middleware is the backbone of modern web development in the .NET ecosystem. It determines how your application responds to errors, how it authenticates users, how it serves files, and how it routes traffic.
Whether you are a beginner just starting with Program.cs or an expert looking to optimize a high-traffic microservice, understanding the request pipeline is non-negotiable. In this guide, we will break down the complexities of middleware, build custom solutions from scratch, and explore the architectural patterns that make ASP.NET Core one of the fastest web frameworks available today.
What is ASP.NET Core Middleware?
Middleware is software assembled into an application pipeline to handle requests and responses. Each component in the pipeline:
- Chooses whether to pass the request to the next component in the pipeline.
- Can perform work before and after the next component in the pipeline is invoked.
Think of it as a chain of responsibility. When a request comes in from a browser, the first middleware executes. It can either terminate the request (short-circuiting) or call the next one. This process continues until the final middleware (usually your Controller or Minimal API endpoint) processes the request and starts sending the response back up the chain.
The Anatomy of the Request Pipeline
In older versions of ASP.NET (System.Web), the pipeline was rigid and heavy. ASP.NET Core changed this by making the pipeline completely modular. You only pay for what you use. If you don’t need static files, you don’t add the middleware. If you don’t need session state, you leave it out. This modularity is why ASP.NET Core is significantly faster than its predecessors.
// A simplified look at how middleware is registered in Program.cs
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
// Middleware 1: Exception Handling
app.UseExceptionHandler("/Error");
// Middleware 2: Static Files (Images, CSS, JS)
app.UseStaticFiles();
// Middleware 3: Routing
app.UseRouting();
// Middleware 4: Authentication
app.UseAuthentication();
// Middleware 5: Authorization
app.UseAuthorization();
// Final Middleware: The Endpoint
app.MapControllers();
app.Run();
The Critical Importance of Order
One of the most common mistakes intermediate developers make is placing middleware in the wrong order. Because middleware executes sequentially, the order in which you call app.Use... methods is vital.
Consider Authentication and Static Files. If you place app.UseStaticFiles() before app.UseAuthentication(), your images and CSS files will be served to everyone, regardless of whether they are logged in. For public assets, this is fine. But if you are serving sensitive reports as static PDFs, you have a security hole.
The standard recommended order is:
- Exception Handling: Catches errors in all subsequent steps.
- HSTS / HTTPS Redirection: Ensures security.
- Static Files: Returns files quickly without hitting the rest of the logic.
- Routing: Determines which endpoint matches the URL.
- CORS: Handles cross-origin requests.
- Authentication: Identifies who the user is.
- Authorization: Determines what the user can do.
- Custom Middleware: Your specific logic.
- Endpoints: Your logic (Controllers/Minimal APIs).
Building Your First Custom Middleware
Sometimes the built-in middleware isn’t enough. Perhaps you need to log every request’s processing time, or you need to validate a custom header for API security. Let’s build a Request Performance Logger.
Method 1: The Inline Lambda (The Quick Way)
For simple logic, you can use app.Use directly in Program.cs.
app.Use(async (context, next) =>
{
// Logic BEFORE the next middleware
var startTime = DateTime.UtcNow;
// Call the next middleware in the pipeline
await next.Invoke();
// Logic AFTER the next middleware
var duration = DateTime.UtcNow - startTime;
Console.WriteLine($"Request to {context.Request.Path} took {duration.TotalMilliseconds}ms");
});
Method 2: The Class-Based Approach (The Professional Way)
For complex logic, you should create a dedicated class. This makes your code testable, reusable, and clean.
using System.Diagnostics;
namespace MyProject.Middleware
{
public class RequestExecutionTimeMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<RequestExecutionTimeMiddleware> _logger;
public RequestExecutionTimeMiddleware(RequestDelegate next, ILogger<RequestExecutionTimeMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
var watch = Stopwatch.StartNew();
// Let the request continue
await _next(context);
watch.Stop();
var elapsedMs = watch.ElapsedMilliseconds;
if (elapsedMs > 500) // Log as warning if request is slow
{
_logger.LogWarning("Slow Request: {Method} {Path} took {Elapsed}ms",
context.Request.Method, context.Request.Path, elapsedMs);
}
}
}
// Extension method for easy registration
public static class RequestExecutionTimeMiddlewareExtensions
{
public static IApplicationBuilder UseRequestExecutionTime(this IApplicationBuilder builder)
{
return builder.UseMiddleware<RequestExecutionTimeMiddleware>();
}
}
}
Now, in your Program.cs, you can simply call app.UseRequestExecutionTime();. This keeps your entry point clean and follows the Single Responsibility Principle.
Step-by-Step: Implementing Global Error Handling
Using try-catch blocks in every controller action is repetitive and error-prone. Instead, we can use middleware to handle exceptions globally.
Step 1: Create an Error Response Model
We want our API to return a consistent JSON structure when something goes wrong.
public class ErrorResponse
{
public int StatusCode { get; set; }
public string Message { get; set; }
public string TraceId { get; set; }
}
Step 2: Create the Middleware
public class GlobalExceptionMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<GlobalExceptionMiddleware> _logger;
public GlobalExceptionMiddleware(RequestDelegate next, ILogger<GlobalExceptionMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
try
{
await _next(context);
}
catch (Exception ex)
{
_logger.LogError(ex, "An unhandled exception occurred.");
await HandleExceptionAsync(context, ex);
}
}
private static Task HandleExceptionAsync(HttpContext context, Exception exception)
{
context.Response.ContentType = "application/json";
context.Response.StatusCode = 500;
var response = new ErrorResponse
{
StatusCode = 500,
Message = "Internal Server Error. Please try again later.",
TraceId = context.TraceIdentifier
};
return context.Response.WriteAsJsonAsync(response);
}
}
Step 3: Register it early
Add app.UseMiddleware<GlobalExceptionMiddleware>(); at the very top of your pipeline in Program.cs so it can catch errors from every other component.
Dependency Injection in Middleware
There is a subtle but critical trap when using Dependency Injection (DI) in middleware. Middleware is typically constructed as a Singleton. It is created once when the application starts and lives for the duration of the app’s life.
The Mistake: Injecting a Scoped service (like an Entity Framework DB Context) into the middleware’s constructor.
The Fix: If you need a scoped service, you must inject it into the InvokeAsync method, not the constructor.
public class UserTrackingMiddleware
{
private readonly RequestDelegate _next;
public UserTrackingMiddleware(RequestDelegate next) // Only Singletons here
{
_next = next;
}
// Inject Scoped services directly into the InvokeAsync method
public async Task InvokeAsync(HttpContext context, MyDbContext dbContext)
{
var userId = context.User.Identity?.Name;
if (userId != null)
{
// Log user activity in the database
// dbContext.UserLogs.Add(...);
// await dbContext.SaveChangesAsync();
}
await _next(context);
}
}
Common Mistakes and How to Avoid Them
- Short-circuiting accidentally: If you forget to call
await next(context), the request stops there. This is useful for security (e.g., “Unauthorized”), but frustrating if done by mistake. - Modifying Headers after Response started: Once you call
next(context), the response might have already started being sent to the client. If you try to add a header after theawait next(context), you will get an exception. Usecontext.Response.OnStartingif you need to modify headers late. - Middleware Overload: Adding too many custom middleware components can slow down your request-response cycle. Always profile your application to ensure the overhead is acceptable.
- Using app.Run vs app.Use: Remember that
app.Run()terminates the pipeline. Any middleware placed afterapp.Run()will never be executed.
Real-World Example: API Key Authentication
Let’s build a practical piece of middleware that checks for a valid X-API-KEY header before allowing access to an API.
public class ApiKeyMiddleware
{
private readonly RequestDelegate _next;
private const string APIKEYNAME = "X-API-KEY";
public ApiKeyMiddleware(RequestDelegate next)
{
_next = next;
}
public async Task InvokeAsync(HttpContext context)
{
if (!context.Request.Headers.TryGetValue(APIKEYNAME, out var extractedApiKey))
{
context.Response.StatusCode = 401;
await context.Response.WriteAsync("API Key was not provided.");
return; // Short-circuit
}
var appSettings = context.RequestServices.GetRequiredService<IConfiguration>();
var apiKey = appSettings.GetValue<string>("ApiKey");
if (!apiKey.Equals(extractedApiKey))
{
context.Response.StatusCode = 401;
await context.Response.WriteAsync("Unauthorized client.");
return; // Short-circuit
}
await _next(context);
}
}
Summary and Key Takeaways
Mastering the middleware pipeline is what separates a junior .NET developer from a senior architect. Here are the core concepts to remember:
- Modularity: ASP.NET Core is built on a series of components that you can opt-in or opt-out of.
- Order is Everything: The sequence in
Program.csdetermines the flow of data and security. - Bi-directional: Middleware processes the request going in AND the response coming out.
- Short-circuiting: You can stop a request from reaching your controllers if it doesn’t meet specific criteria (like authentication).
- DI Awareness: Always inject Scoped services into the
InvokeAsyncmethod, never the constructor.
Frequently Asked Questions (FAQ)
1. What is the difference between Middleware and Filters?
Middleware operates at the HTTP level and has access to the HttpContext. It runs for every request. Filters (like Action Filters or Result Filters) run within the MVC/Routing context and have access to things like ModelState and ActionDescriptor. Use Middleware for cross-cutting concerns like logging or security, and Filters for logic specific to your Controllers.
2. Can I use Middleware to rewrite URLs?
Yes, ASP.NET Core provides built-in URL Rewriting Middleware. You can also write your own to modify context.Request.Path before the Routing middleware sees it.
3. Does the order of middleware affect performance?
Yes. You should place middleware that can “short-circuit” the request (like StaticFiles or ResponseCaching) as early as possible to avoid running heavy logic (like Authentication or Database hits) unnecessarily.
4. How do I conditionally run middleware?
You can use app.Map() or app.UseWhen(). For example, you can use app.UseWhen(context => context.Request.Path.StartsWithSegments("/api"), appBuilder => ...) to run specific middleware only for API calls while ignoring regular web page requests.
5. Is Middleware thread-safe?
Because middleware is a singleton, it must be thread-safe. Avoid storing request-specific data in class fields. Always use the HttpContext or scoped services to store information for the duration of a request.