Hosting and the request pipeline

Every ASP.NET Core app starts the same way:

var builder = WebApplication.CreateBuilder(args); // configuration, logging, DI
builder.Services.AddSingleton<IClock, SystemClock>();

var app = builder.Build();                        // the container is now fixed

app.Use(async (context, next) =>
{
    // runs on the way in
    await next(context);
    // runs on the way out
});

app.MapGet("/orders/{id:int}", (int id) => Results.Ok(id));

app.Run();                                        // start Kestrel and block

CreateBuilder loads configuration, sets up logging and gives you an empty IServiceCollection. Build() turns that collection into the root service provider; after it, builder.Services is read-only and adding a registration throws. Everything after Build() describes the request pipeline, and Run() starts the server.

A pipeline is one delegate

A RequestDelegate is a function Task (HttpContext). A middleware is a function that takes the next delegate and returns a new one that wraps it: Func<RequestDelegate, RequestDelegate>. app.Use only appends one of those to a list. When the pipeline is built, the list is folded from the last component to the first, each one wrapping everything after it. The innermost next is a terminal delegate that answers 404 when no endpoint handled the request. The result is a single delegate, and the server calls it once per request.

The example models this with plain delegates: two components and the 404 terminal.

Code before next runs on the way in, in registration order. Code after next runs on the way out, in reverse. The first component registered is the outermost layer: a stopwatch there times the whole request, and an exception handler there sees every exception thrown below it.

Built once, run many times

The second model separates the two phases: three component factories, one build, two requests.

The factories run once, last first, when the pipeline is built; the delegates they return run on every request, first first. This is why a convention-based middleware class (app.UseMiddleware<T>()) is constructed only once for the life of the app. A scoped service such as a DbContext must therefore be a parameter of its InvokeAsync method, not of its constructor.

The response can start before you get control back

As soon as an endpoint writes to the response body, the status line and headers are sent to the client and context.Response.HasStarted becomes true. Code that runs after await next(context) may be too late: setting a header at that point throws an InvalidOperationException. Set headers before calling next, or register a callback with context.Response.OnStarting(...), which runs just before the headers go out.

Common mistakes

• Calling next(context) without await. The code after it runs while the inner components are still working, and an exception they throw never reaches this middleware's try/catch.
• Setting a response header after await next(context). It works in a test where the endpoint writes nothing and throws in production where it writes a body.
• Injecting a scoped service into a middleware class's constructor. The class is built once, so the first request's instance is reused forever (the factory in the second model ran once for two requests).