What is middleware, how does the request pipeline work, why does order matter, and how do you write custom middleware?

Say it out loud, then check

One request, every middleware, in and out

One real request through the lending API pipeline. Down the left column on the way in, then the right column on the way back up. The response fills in below.

The story

1. Before

   In .NET Framework, IIS, the Windows web server, ran every ASP.NET request through a fixed list of events. Shared code hooked into those events from Global.asax or an IHttpModule listed in web.config.

   IISWindows web server

   BeginBeginRequest

   AuthAuthenticateRequest

   Handleryour page or controller

   1/5IIS ran every request through the same fixed events, for every app, in IIS's order.Shared code, like logging, hooked into an event with an IHttpModule.Which modules ran sat in web.config, not in code. You could not read the order in one place.And it all lived in System.Web, a library tied to IIS, so the app ran only on Windows.ASP.NET Core: the pipeline is plain code in Program.cs, in the order you write.

   BackPlayNext
2. Why it had to change

   The order was hidden in IIS and web.config, and the app could not run outside IIS.

3. How it works now

   ASP.NET Core made the pipeline an ordered list of functions in Program.cs. Each one gets the HttpContext and a next to call. Kestrel, the web server built into the app, feeds requests into the top.

4. What happens next

   The pipeline is now code you read top to bottom. The storyboard below follows one real payment through all of it.

5. What we gained

   You read the order in one file and can test it. A shared job is written once instead of in 40 controllers. And the same app runs on Kestrel anywhere: App Service, a container, Linux.

In the lending API

Program.cs runs once at start-up. The app.Use… lines build the pipeline: a request passes them top to bottom, the response bottom to top.

Only the key lines are shown; Deep walks the whole file.

The code, file by file

The BMW FS lending API: the pipeline in Program.cs, our custom middleware, and the controller at the end of the line. Tap a line to see where the request is.

What they ask next

The follow-ups interviews really ask. Answer out loud, then tap to check.

• ReportedWhat is the difference between app.Use and app.Run?

  Use adds a middleware that gets next: it can work before and after the rest of the pipeline, or stop early. Run adds a terminal one: no next, so nothing after it ever runs.

  app.Use(async (ctx, next) =>
  {
    var sw = Stopwatch.StartNew();
    await next(ctx);   // or next(): same
    app.Logger.LogInformation(
      "{Ms} ms", sw.ElapsedMilliseconds);
  });
  app.Run(ctx =>
    ctx.Response.WriteAsync("pong"));
  app.UseAuthorization(); // never reached

  Diagram + next questions →Where this was reported
• ReportedWhy does middleware order matter? Give an example.

  Requests meet them in exactly the Program.cs order. Exception handler first, so it catches everything below. Authentication before authorization, or every call is 401. CORS before both, or the browser's no-token preflight check gets 401.

  Next questions, in Deep →See the order bug animated →Where this was reported
• ReportedMiddleware vs filters: what is the difference?

  Middleware runs for every request and knows only the HttpContext. Filters run only around MVC actions and can see the action, its arguments and the model state. App-wide jobs are middleware; rules for some actions are filters. Full answer: the filters card (Related).

  Next questions, in Deep →Where this was reported

Follow-up tree

Answer, then open the next level. That is the order an interviewer digs in.

Reporteda candidate was asked Intervieweran interviewer asks it

• ReportedWhat is the difference between app.Use and app.Run?

  Use adds a middleware that gets next: it can work before and after the rest of the pipeline, or stop early. Run adds a terminal one: no next, so nothing after it ever runs.

  app.Use(async (ctx, next) =>
  {
    var sw = Stopwatch.StartNew();
    await next(ctx);   // or next(): same
    app.Logger.LogInformation(
      "{Ms} ms", sw.ElapsedMilliseconds);
  });
  app.Run(ctx =>
    ctx.Response.WriteAsync("pong"));
  app.UseAuthorization(); // never reached

  app.Use: timergets next

  GET /ping

  timer: running

  app.Run: "pong"no next: the end

  app.Use: anything elseafter a Run

  1/4Use: start the timer, then call next.Run: writes "pong" and returns. It has no next to call.Anything added after a Run is never reached.Back up in Use: the code after await next runs and logs the time.

  BackPlayNext

  Where this was reported
  • What does app.Map do?

    It branches the pipeline by the start of the path. Requests to /internal/... go down the branch's own small pipeline and never return to the main line. MapWhen branches on any condition; UseWhen branches and then rejoins. Don't confuse it with MapGet or MapControllers, which add endpoints, not branches.

    app.Map("/internal", branch =>
    {
      // checks an X-Api-Key header
      branch.UseMiddleware<ApiKeyMiddleware>();
      branch.Run(ctx => ctx.Response
        .WriteAsync("internal ok"));
    });

  • Explain this lineProgram.cs ends with app.Run(). Is that the Run middleware?

    No. With no arguments, app.Run() starts the web server and waits until the app stops. The terminal middleware is app.Run(context => ...), with a function. Same name, different job.

  • What is short-circuiting? Give real examples.

    A middleware writes the response and does not call next, so nothing below runs. Everyday ones: authorization returning 401 or 403, CORS answering a browser's preflight, the rate limiter returning 429 (once RejectionStatusCode is set; the default is 503), static files returning a file. That is also why the exception handler and request logging go above them: they must see every request.

• ReportedWhy does middleware order matter? Give an example.

  Requests meet them in exactly the Program.cs order. Exception handler first, so it catches everything below. Authentication before authorization, or every call is 401. CORS before both, or the browser's no-token preflight check gets 401.

  See the order bug animated →Where this was reported
  • Where does UseCors go, and what breaks if it is wrong?

    After UseRouting, before UseAuthentication and UseAuthorization. Before a cross-site call with a token, the browser first sends a preflight: an OPTIONS request with no token, asking which sites may call. Most secure APIs set a fallback policy (every endpoint needs a signed-in user), so if authorization runs first, the preflight gets 401 with no CORS headers, and the browser reports a CORS error while the API is up. Postman and integration tests never send preflights, so only real browsers fail.

    See the production incident →
  • Why is the exception handler first?

    It wraps the rest of the pipeline in a try/catch. Anything thrown below it, in auth, our middleware or a controller, climbs back to it and becomes a 500 ProblemDetails with a trace id, instead of a dropped connection or a stack trace. Anything above it is not covered. One limit: if the response has already started, it can only log. In .NET 8 the handling logic goes in an IExceptionHandler; the global handler is its own card (Related).

  • ReportedHow does authentication work in a Web API?

    The authentication middleware reads the Bearer token from the Authorization header. It checks that Entra ID (Microsoft's sign-in service) signed it, that it was issued for this API, and that it has not expired, then puts the claims in HttpContext.User. A request with no token is not rejected here; the user is just empty. Authorization then checks policies and roles against that user. The full flow, from login to refresh, is its own card (Related: JWT authentication).

• ReportedMiddleware vs filters: what is the difference?

  Middleware runs for every request and knows only the HttpContext. Filters run only around MVC actions and can see the action, its arguments and the model state. App-wide jobs are middleware; rules for some actions are filters. Full answer: the filters card (Related).

  Where this was reported
• Conventional middleware or IMiddleware: what is the difference?

  A conventional class (constructor takes RequestDelegate next, method InvokeAsync(HttpContext)) is built once, so it behaves like a singleton; scoped services go in InvokeAsync's parameters. A class that implements IMiddleware is registered in the container and built per request with the lifetime you give it, so its constructor can take scoped services. I default to conventional, and use IMiddleware when the constructor needs something scoped.

  // C# 12 primary constructor: db is a
  // constructor parameter.
  public sealed class AuditMiddleware(
    ServicingDbContext db) : IMiddleware
  {
    public async Task InvokeAsync(
      HttpContext ctx, RequestDelegate next)
    {
      await next(ctx);
      // AuditRows: a DbSet<AuditRow> on our
      // context; AuditRow is a small record.
      db.AuditRows.Add(new AuditRow(
        ctx.Request.Path,
        ctx.Response.StatusCode));
      await db.SaveChangesAsync();
    }
  }
  // Program.cs: per request, UseMiddleware
  // asks the container for a new one.
  builder.Services.AddScoped<AuditMiddleware>();
  app.UseMiddleware<AuditMiddleware>();

  • How do you use a scoped service, like a DbContext, in conventional middleware?

    Add it as a parameter of InvokeAsync after the HttpContext. ASP.NET Core resolves it from the request's scope on every call. Never put it in the constructor.

    See the captive bug animated →
• Your logging middleware logs request headers and bodies. What can go wrong?

  It copies secrets and personal data into logs that many people can read and that are kept for months: the Authorization header holds the dealer's token, and a payment body holds bank details. I log an allow-list only: method, path, status, duration, correlation id. If I need more, the built-in UseHttpLogging with an allow-list of headers, and never the body on money endpoints. Reading the body also needs EnableBuffering, or the controller finds it empty.

• How would you test a middleware?

  Two levels. A unit test builds a DefaultHttpContext, passes a fake next that records it was called, and checks what it can see without a server: that next ran and what was put on the context. OnStarting callbacks only run when a real response starts, so the header is checked in the integration test: WebApplicationFactory sends real requests through the real pipeline, the only way to test order too. For CORS that test sends an OPTIONS preflight with an Origin header and asserts the allow header comes back.

  var ctx = new DefaultHttpContext();
  var called = false;
  RequestDelegate next = _ =>
  {
    called = true;
    return Task.CompletedTask;
  };
  var mw = new CorrelationIdMiddleware(
    next, NullLogger<
      CorrelationIdMiddleware>.Instance);
  await mw.InvokeAsync(ctx);
  Assert.True(called);

Production bugs, and how to tell them

Each one: what you see, why, the fix in code, and the line to say.

• Every protected call returns 401 after a refactor

  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: Bearer
  
  Every [Authorize] endpoint, even with a valid token.
  No exception in the logs.

  Cause

  UseAuthorization sat above UseAuthentication. When authorization checked the user, nobody had read the token yet, so HttpContext.User was empty.

  Fix

  Swap the two lines. Add an integration test that calls one protected endpoint with a valid test token and expects 200.

  BeforeAfter

  Diagram · step 1A dealer calls with a valid token. It sits in the request; nobody has read it yet.Show diagram

  GET /loans/7781

  token: in the request

  UseAuthorizationchecks the user

  UseAuthenticationreads the token

  LoansControllerthe endpoint

  1app.UseExceptionHandler();2app.UseRouting();3app.UseAuthorization();4app.UseAuthentication();5app.MapControllers();

  Before · Program.cs · line 2 · 1 of 3A dealer calls with a valid token. It sits in the request; nobody has read it yet.

  BackNext line

  Say it

  Authentication answers "who are you" and fills HttpContext.User; authorization answers "may you" using that user. Run them backwards and authorization always sees an anonymous caller, so everything is 401. It is silent: no exception, only 401s.

• A header set after the response started

  System.InvalidOperationException: Headers are read-only, response has already started.
     at Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http.HttpHeaders.ThrowHeadersReadOnlyException()
     at Lending.Api.Middleware.CorrelationIdMiddleware.InvokeAsync(HttpContext context)
  warn: Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware
        The response has already started, the error handler will not be executed.

  Cause

  The first version of our middleware set X-Correlation-ID after await _next(context). By then the controller had written the body, and headers always leave before the body.

  Fix

  Book the header with OnStarting before calling next. ASP.NET Core runs that callback just before the headers are sent.

  BeforeAfter

  Diagram · step 1The middleware picks an id for this request: 9f3c.Show diagram

  Our middlewareCorrelationIdMiddleware

  1public async Task InvokeAsync(2 HttpContext context)3{4 var id = GetOrCreateId(context);5 await _next(context);6 context.Response.Headers[Header] = id;7}

  Before · CorrelationIdMiddleware.cs · line 4 · 1 of 3Same helper as in the code walk above: the caller's id, or this request's TraceIdentifier.

  BackNext line

  Say it

  Headers travel before the body, so once the first byte of the body is sent they are locked. Code after next() runs too late to add one; OnStarting is the hook for it. The client still got its 201, which is why this hid in the logs for a week.

• A DbContext in a middleware's constructor

  Development:
  System.InvalidOperationException: Cannot resolve scoped service 'Lending.Infrastructure.Servicing.ServicingDbContext' from root provider.
  
  Production (scope checks off), under load:
  System.InvalidOperationException: A second operation was started on this context instance before a previous operation completed.

  Cause

  A middleware class is built once, when the pipeline is built, from the root provider. DealerStatusMiddleware took the scoped ServicingDbContext in its constructor, so one context served every request. In Development the container's scope check (ValidateScopes) catches it at start-up; in Production that check is off by default, so it only shows under load.

  Fix

  Ask for the context as an InvokeAsync parameter. ASP.NET Core fills those from the current request's scope on every call.

  BeforeAfter

  Diagram · step 2The context goes into a field. It now lives as long as the app: a captive dependency.Show diagram

  Root providerbuilds the middleware once

  DealerStatusMiddlewareone for the app

  _db

  ServicingDbContextregistered: scoped

  1public sealed class DealerStatusMiddleware2{3 private readonly RequestDelegate _next;4 private readonly ServicingDbContext _db;5 6 public DealerStatusMiddleware(7 RequestDelegate next,8 ServicingDbContext db)9 { _next = next; _db = db; }10 11 public async Task InvokeAsync(12 HttpContext context)13 {14 var id = context.User15 .FindFirstValue("dealer_id");16 var active = await _db.Dealers17 .AnyAsync(d => d.Id == id && d.Active);18 if (!active)19 {20 context.Response.StatusCode = 403;21 return;22 }23 await _next(context);24 }25}

  Before · DealerStatusMiddleware.cs · line 4 · 1 of 4A field lives as long as the object. This object lives as long as the app.

  BackNext line

  Say it

  Conventional middleware behaves like a singleton. Its constructor parameters are resolved once, from the root; its InvokeAsync parameters are resolved per request. So singletons go in the constructor and scoped services go in InvokeAsync. It is the same captive dependency as in the lifetimes card.

Traps

• Don't sayMiddleware runs only on the way in.SayCode before next() runs on the way in; code after it runs on the way out, in reverse order.
• Don't sayASP.NET Core sorts the middleware for you.SayThey run exactly in the order written. A wrong order compiles and fails at run time.
• Don't sayPut the DbContext in the middleware's constructor.SayThe class is built once. Scoped services go in InvokeAsync's parameters.
• Don't sayAdd the response header after await next().SayBy then the body has started and headers are locked. Use OnStarting.
• Don't sayFix a CORS error by allowing any origin.SayFirst check the order: CORS must run before authentication, or the preflight gets 401.

Traps

What should you say instead? Tap to check.

• Don't sayMiddleware runs only on the way in.

  Say instead

  Code before next() runs on the way in; code after it runs on the way out, in reverse order.

• Don't sayASP.NET Core sorts the middleware for you.

  Say instead

  They run exactly in the order written. A wrong order compiles and fails at run time.

• Don't sayPut the DbContext in the middleware's constructor.

  Say instead

  The class is built once. Scoped services go in InvokeAsync's parameters.

• Don't sayAdd the response header after await next().

  Say instead

  By then the body has started and headers are locked. Use OnStarting.

• Don't sayFix a CORS error by allowing any origin.

  Say instead

  First check the order: CORS must run before authentication, or the preflight gets 401.