ASP.NET Core Middleware Explained: The Request Pipeline

Every request goes in through the chain. The response comes back out through it too.

Lesson 253 told you that a request passes "through the middleware pipeline" on its way to your handler. That phrase is doing a lot of work, and this lesson unpacks exactly what's inside it. Middleware is one of the most important ideas in ASP.NET Core — and also one of the most commonly half-understood, because most tutorials show you that it exists without ever showing you the mental model that makes its behavior predictable.

Here's the model, stated up front: middleware isn't a one-way filter that requests pass through once. It's a chain where each link can act before handing off to the next link, and then act again after that next link is completely finished — including everything it did, all the way down to your endpoint and back. Once that clicks, middleware order stops being a mystery you memorize and becomes something you can reason about.

In this lesson, you'll learn the real execution model behind ASP.NET Core middleware — the "onion" — how to write your own with app.Use(...), tour the built-in middleware you've likely already used without knowing its name, and understand exactly why order is not a cosmetic detail but a correctness requirement.

What Is It?

The Simple Explanation

Middleware is a small piece of code that sits in the path of every request flowing through your app. Each piece of middleware gets a chance to look at (and change) the incoming request, and then it makes one of two choices: pass the request along to the next piece of middleware in line, or stop the chain right there and produce the response itself.

The Technical Definition

Formally, middleware is a component, registered in a specific order, that forms part of an application's request pipeline. Each component is represented internally as a RequestDelegate — a function that takes an HttpContext and returns a Task. Components are composed together: each one is handed a reference to the next delegate in the chain, and it decides when — or whether — to invoke it. This produces the defining property of ASP.NET Core middleware: a component can run code both before the next component executes and after it returns, because calling "next" is just an ordinary awaited function call sitting in the middle of the component's own code.

Why Does It Exist?

The Problem — Cross-Cutting Concerns Don't Belong in Every Handler

Every real web app needs a handful of things done for every single request, regardless of which endpoint it eventually reaches: logging, exception handling, redirecting HTTP to HTTPS, checking authentication, serving static files. Without a pipeline concept, you'd be forced to either duplicate that logic inside every single endpoint handler, or wire up some ad-hoc, framework-specific mechanism for each concern (which is close to what classic ASP.NET's fixed HttpModule pipeline required — heavier, and much harder to reorder or compose freely).

The Solution — A Composable Chain You Control

ASP.NET Core's answer is a plain, explicit chain of delegates that you assemble yourself, line by line, in Program.cs. There's no hidden framework magic deciding what runs when — the order you write app.Use...() calls in is the order things execute in. Any cross-cutting concern that applies broadly to many or all requests becomes one small, focused, independently testable component, instead of scattered copy-pasted logic.

Big Picture

This is the correct mental model for ASP.NET Core middleware — nested layers, like an onion or a Russian nesting doll, not a one-way conveyor belt:

Request
   │
   ▼
┌─────────────── Middleware A ───────────────┐
│  (before next)                              │
│   ┌────────────── Middleware B ───────────┐ │
│   │  (before next)                        │ │
│   │   ┌──────────── Middleware C ───────┐ │ │
│   │   │  (before next)                  │ │ │
│   │   │      ┌──────── Endpoint ────┐   │ │ │
│   │   │      │   your handler runs  │   │ │ │
│   │   │      └───────────────────────┘   │ │ │
│   │   │  (after next returns)           │ │ │
│   │   └──────────────────────────────────┘ │ │
│   │  (after next returns)                  │ │
│   └────────────────────────────────────────┘ │
│  (after next returns)                        │
└───────────────────────────────────────────────┘
   ▲
   │
Response

Notice the shape: Middleware A's "before" code runs first, then it calls into B, whose "before" code runs, which calls into C, and so on down to the endpoint. But the "after" code doesn't run in that same order — it unwinds in exactly the reverse sequence: C's after-code runs first, then B's, then A's, last. This is precisely what a nested function call does, because that's exactly what it is under the hood.

How It Works

app.Use(async (context, next) =>
{
    // code here runs BEFORE the rest of the pipeline
    await next(context);
    // code here runs AFTER the rest of the pipeline has finished
});

app.Use(async (context, next) =>
{
    if (!context.Request.Headers.ContainsKey("X-Api-Key"))
    {
        context.Response.StatusCode = 401;
        await context.Response.WriteAsync("Missing API key");
        return; // never calls next() — nothing further in the chain runs
    }
    await next(context);
});

Simple Example

A timing middleware that logs how long each request took — a textbook use of the "before / after" shape:

app.Use(async (context, next) =>
{
    var stopwatch = Stopwatch.StartNew();

    await next(context); // everything downstream runs here — routing, the endpoint, all of it

    stopwatch.Stop();
    Console.WriteLine($"{context.Request.Method} {context.Request.Path} → {context.Response.StatusCode} ({stopwatch.ElapsedMilliseconds}ms)");
});

What happens: the stopwatch starts, then the entire rest of the pipeline runs — every other middleware, routing, model binding, your handler, all of it — as one unit represented by that single await next(context) call. Only once everything downstream has finished and a response has been produced does execution resume on the line after it, where the elapsed time and the final status code (now correctly populated) get logged. This only works correctly because middleware runs code both before and after the chain — a plain "before only" filter couldn't know the final status code, because nothing downstream would have run yet.

Real-World Example

You've almost certainly used all of these built-in middleware components already, without ever seeing them named. Here's a representative Program.cs for a typical API, with the correct, standard order:

var app = builder.Build();

app.UseExceptionHandler("/error");   // catches unhandled exceptions from everything below it
app.UseHttpsRedirection();           // redirects plain HTTP requests to HTTPS
app.UseStaticFiles();                // serves files from wwwroot before routing even runs
app.UseRouting();                    // matches the request to an endpoint (often implicit — see below)

app.UseAuthentication();             // establishes WHO the caller is
app.UseAuthorization();              // decides WHETHER that caller is allowed to proceed

app.MapControllers();                // the endpoints themselves
app.Run();

• UseExceptionHandler — wraps everything below it; if any of it throws, this middleware's "after" code catches the exception on the way back up and produces an error response instead of a crash.
• UseHttpsRedirection — inspects the incoming request before passing it on; if it's plain HTTP, short-circuits with a redirect response instead of calling next.
• UseStaticFiles — if the request path matches a file under wwwroot, it short-circuits and serves the file directly, skipping routing and your endpoints entirely.
• UseRouting / UseAuthentication / UseAuthorization — this is the sequence that matters most, explained next.

Analogy

Under the Hood

Common Confusion

"Middleware runs once per request" — true, but misleading

It's tempting to picture each middleware as executing exactly one block of code and moving on, like a conveyor belt station. In reality, one middleware component's code runs in two separate moments for the same request: once on the way in (before next), and once on the way back out (after next returns) — with the entire rest of the pipeline having executed in between. The onion model, not the conveyor belt, is the accurate picture.

Does routing have to be registered explicitly?

In older ASP.NET Core code you'll often see explicit app.UseRouting() and app.UseEndpoints(...) calls, with everything endpoint-related nested inside UseEndpoints. In the modern minimal hosting model (a single top-level Program.cs, as used throughout this course), calling app.MapGet(...)/app.MapControllers() and friends is enough — the framework inserts the routing middleware at the correct point in the pipeline automatically. The underlying rule stays the same either way: whatever depends on the matched endpoint (like authorization) must still be positioned so routing has already run by the time it executes. When in doubt about a specific, less common ordering scenario, it's worth confirming against the current official ASP.NET Core middleware documentation rather than assuming.

Common Mistakes

Mistake 1 — Forgetting to call next()

Writing a middleware that's meant to just inspect or log the request, but forgetting to call await next(context) at all. Every request silently stops dead at this middleware — no endpoint, and nothing registered after it, ever runs.

Unless you deliberately intend to short-circuit (produce the entire response yourself), always call next.

Mistake 2 — UseAuthorization() before UseAuthentication()

Placing authorization before authentication in Program.cs. Authorization checks run against an identity that hasn't been established yet — requests get incorrectly rejected because the authorization system sees no authenticated user at all.

UseAuthentication() always comes before UseAuthorization() — this specific order is required and well documented, not a stylistic preference.

Mistake 3 — Writing to the response after it's already started

Trying to set a header or status code in "after next()" code, once a downstream component has already begun streaming the response body. This throws an InvalidOperationException — headers can't change after the response has started being sent.

Middleware that needs to modify response headers based on the outcome should do so carefully, checking whether the response has already started (context.Response.HasStarted) before attempting to.

When Should I Use It?

Write custom middleware when:

• The concern genuinely applies broadly — to all requests, or to a whole class of requests — regardless of which specific endpoint handles them (logging, correlation IDs, global exception handling, CORS).
• You need to act on the raw HTTP request/response, before routing has even decided which endpoint applies.

Reach for something else when:

• The concern needs to know MVC-specific details — the matched action, its bound arguments, model validation state — none of which plain middleware has access to. That's what filters exist for (lesson 255).
• The concern only applies to a handful of specific Minimal API endpoints, not the whole app — endpoint filters (lesson 256) are usually a better fit than a broad middleware component with conditional logic inside it.

Mental Model

Key Takeaway

Check Your Understanding

You've seen the onion model and toured the built-in middleware you've likely already used. Let's check the mental model has stuck.

You now understand the onion model that governs every request in ASP.NET Core — and exactly why middleware order isn't negotiable.