The Middleware Pipeline, in Miniature

"So, naturalists observe, a flea / Hath smaller fleas that on him prey; / And these have smaller still to bite 'em; / And so proceed ad infinitum." — Jonathan Swift, On Poetry: A Rhapsody (1733)

Swift's fleas are a joke about critics and an exact description of a request pipeline. Each piece of middleware sits on top of the next, which sits on top of the next, down to the one that finally does the work — and on the way back out, each of them gets another turn in reverse. Understanding ASP.NET Core begins and very nearly ends with understanding that shape, because almost every behaviour people find surprising about it is a consequence of what wraps what.

This Part assembles the pieces the last one built into something that serves requests. The container, the lifetimes, the configuration and the host are all present in a web application, and the one genuinely new idea is this: the request pipeline. So we build it, in about fifteen lines, and then use it to explain the behaviours that would otherwise be rules to memorise.

Build the pipeline

The entire mechanism is a list of functions and a fold.

The output is the shape people draw as an onion: logging → auth → routing → HANDLER → routing → auth → logging. Every middleware sees the request going in and the response coming back out, in opposite orders.

The type is where the design lives. A middleware is (Context, Func<Task>) → Task — it receives the request and a function that represents the entire rest of the application. It may call that function, or not; before doing other work, or after; once, or never. Everything a pipeline can do follows from having the remainder of the work available as a value.

Build is the only clever line, and the cleverness is in the direction. It folds from the end backwards, because each middleware must close over the one that follows it, and that one has to exist first. Note var following = next; — capturing into a fresh local each iteration rather than using the loop variable, which is precisely the closure trap from Part III's LINQ chapter. Without it every middleware would capture the same variable and the pipeline would wire itself into a loop.

The result is a single Func<Context, Task>. By the time a request arrives there is no list, no iteration and no dispatch — just nested closures that already exist.

Order is the design

A pipeline has no configuration file. The sequence of Use calls is the configuration.

Two identical middleware, one line moved, and one application logs request by ada while the other logs request by (unknown). Nothing is misconfigured in the second; the log line simply executes before the thing that would have told it who the user was.

This is why the conventional ordering is worth understanding rather than copying. Every rule in that table is derivable from the onion:

Exception handling goes first because it is a try/catch around next(), and a try cannot catch what already happened above it. Authentication precedes authorisation because the second asks "may this user do that?" and needs the answer to "which user?". Authorisation precedes the endpoint because rejecting after doing the work has already cost you the work — and, worse, may have written to a database. Static files go early because serving a file needs none of the machinery below it. Compression goes outside most things because it operates on the way back out, and the response must exist before it can be compressed.

None of those is a rule to memorise. They are five consequences of one picture.

Short-circuiting

A middleware that declines to call next() is not broken. It is how a pipeline says no, and how it answers without doing the work.

Three requests, and the expensive handler ran once. The rejected request stopped at authentication; the cached one stopped at the cache. Neither reached the endpoint, and neither paid for it.

The detail worth noticing is in the traces: when a middleware short-circuits, the after halves of everything above it still run. Logging still logged, with the 401 status the auth middleware had just set. That is the onion again — the short circuit cut the inner layers out, and the outer ones completed normally on the way back. It is why a logging middleware at the top sees every response, including the ones no endpoint ever produced.

This is also the mechanism behind a large share of what a real framework ships. Static file serving, response caching, rate limiting, CORS preflight handling, health check endpoints and authorisation failures are all middleware that decide, sometimes, not to call next().

Exception handling, and what it cannot catch

Error-handling middleware is the clearest case of behaviour following directly from position.

Registered first, it catches the endpoint's exception and turns it into a 500 with a body. Registered second, the same exception from a middleware above it escapes the pipeline entirely — the status is still 200 and nothing wrote a response, because nothing caught it.

The implementation explains both outcomes completely. An exception handler is a try around await next(). next() is the rest of the pipeline. Therefore it sees exceptions from everything downstream and is structurally incapable of seeing anything upstream. "Register it first" is not a convention; it is the only position from which it works.

The other detail in that first trace is worth pausing on: routing's after line never ran. An exception thrown downstream unwinds through every middleware between the throw and the catch, so the code after their await next() is skipped. If a middleware needs to do something on the way out regardless — stopping a timer, releasing something, writing a metric — it needs a try/finally of its own. The after half of a middleware is not a guarantee, it is just the next statement.

Composed once

The pipeline is assembled at startup, and that has a consequence for state that catches people.

The counter climbs 1, 2, 3, 4, 5 across five requests, because the middleware object was constructed once and captured into the composed delegate. Every request runs through the same instance.

That makes a middleware field singleton state, and the whole of Part V's lifetimes chapter applies to it without modification. It must be thread-safe, because requests arrive concurrently and that field is shared. It must not hold anything scoped, or it is a captive dependency — which is why a real middleware that needs a scoped service takes it as a parameter on Invoke rather than in its constructor, so the framework can resolve it per request. And anything that genuinely belongs to one request goes on the context, which is what the items dictionary is for.

The allocation figures say the composition is worth caching: a request through the built pipeline costs 432 bytes, and a request that rebuilds the pipeline first costs 680. The difference is the Build call, and it scales with the number of middleware while the per-request cost does not. Three middleware is a small penalty; a realistic pipeline of twenty would not be.

Common Mistakes

1. Registering exception handling after something that can throw. It is a try around next(), so it cannot see anything above it. Anything that throws upstream escapes the pipeline entirely.

2. Putting authorisation after the endpoint. The work happens and is then rejected, which costs the work and may have already written to a database.

3. Expecting the code after await next() to always run. A downstream exception unwinds straight past it. Use try/finally if it must happen.

4. Mutable fields on a middleware class. The instance is a singleton shared by every concurrent request, so an unsynchronised field is the data race from Part IV.

5. Injecting a scoped service into a middleware constructor. That is a captive dependency. Take it as a parameter on Invoke so it is resolved per request.

6. Writing to the response after calling next(). By then the response may have started being sent, and headers in particular can no longer be changed.

7. Thinking a short circuit skips everything. It skips what is below it; the after halves of everything above still run and still see the response.

8. Building the pipeline inside the request path. The composition is startup work, and paying it per request adds a cost that scales with pipeline length.

9. Capturing the loop variable when composing by hand. Each iteration must capture a fresh local, or every middleware closes over the same variable.

10. Treating middleware order as style. It is the behaviour. Two identical registrations in different orders are two different applications.

Interview Corner

Hands-on

Run it unchanged first: ten failures and score 0/10. A stub that scores above zero means a check is not testing what it claims.

Summary

• A pipeline is a list of functions folded into nested closures. Each middleware receives the request and a delegate representing the entire rest of the application.
• Build folds from the end backwards, because each middleware must close over the one after it — capturing a fresh local each iteration, or they all close over the same variable.
• The onion is the shape: every before in registration order, the handler, then every after in reverse. A middleware sees both the request and the response.
• Order is the configuration. Identical middleware with two lines swapped produced request by ada and request by (unknown) from the same application.
• The conventional ordering is derivable, not arbitrary — errors first because a try cannot catch upstream, authentication before authorisation, authorisation before the work it would reject.
• Declining to call next() short-circuits the rest, which is how rejection, caching, static files and rate limiting avoid paying for the endpoint.
• A short circuit skips only what is below it. The after halves above still run and still see the response.
• Exception middleware is a try around next(), so it catches everything downstream and nothing upstream — and a thrown exception unwinds past the after code of everything in between.
• A middleware instance is a singleton. Its fields are shared by concurrent requests, so a scoped dependency belongs on Invoke and per-request state belongs on the context.
• Composition is startup work: 432 bytes for a request on a built pipeline against 680 for one that rebuilds first, and the gap grows with pipeline length.

In the next chapter, Minimal APIs, Binding and Validation, we reach the end of the pipeline: how a route pattern becomes a method call, where the arguments to that method come from, what happens when the incoming data does not fit the parameters it is supposed to fill, and why returning the right status code is harder than it looks.