ASP.NET Core Middleware Explained — Pipeline, Order & Custom Middleware

// Program.cs — stripped-down app to visualise the two-phase pipeline
// Run this and watch the console output to see requests flow IN and OUT

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Middleware A — outermost layer (first in, last out)
app.Use(async (context, next) =>
{
    Console.WriteLine("[A] Incoming — path: " + context.Request.Path);
    
    await next(context);   // hand control to the next middleware
    
    // This line runs AFTER the inner middlewares have all finished
    Console.WriteLine("[A] Outgoing — status: " + context.Response.StatusCode);
});

// Middleware B — middle layer
app.Use(async (context, next) =>
{
    Console.WriteLine("[B] Incoming");
    await next(context);
    Console.WriteLine("[B] Outgoing");
});

// Terminal middleware — writes the response, does NOT call next
app.Run(async context =>
{
    Console.WriteLine("[Terminal] Writing response");
    context.Response.StatusCode = 200;
    await context.Response.WriteAsync("Hello from the pipeline!");
});

app.Run();

// RequestTimingMiddleware.cs
// Measures how long each request takes and logs it.
// ILogger<T> is a singleton-safe service — safe to inject in constructor.
// A scoped service like a DbContext would go on InvokeAsync instead.

using System.Diagnostics;

public class RequestTimingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<RequestTimingMiddleware> _logger;

    // Constructor injection: only use singleton or transient services here
    public RequestTimingMiddleware(
        RequestDelegate next,
        ILogger<RequestTimingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    // InvokeAsync is called by the framework for every request
    // Scoped services (e.g. AppDbContext) can be injected here as parameters
    public async Task InvokeAsync(HttpContext context)
    {
        var stopwatch = Stopwatch.StartNew();

        // --- INCOMING: before the rest of the pipeline runs ---
        _logger.LogInformation(
            "Request started: {Method} {Path}",
            context.Request.Method,
            context.Request.Path);

        await _next(context); // run the rest of the pipeline

        // --- OUTGOING: after the response has been produced ---
        stopwatch.Stop();

        _logger.LogInformation(
            "Request finished: {Method} {Path} — {StatusCode} in {ElapsedMs}ms",
            context.Request.Method,
            context.Request.Path,
            context.Response.StatusCode,
            stopwatch.ElapsedMilliseconds);
    }
}

// MiddlewareExtensions.cs
// A clean extension method makes registration readable in Program.cs
public static class RequestTimingMiddlewareExtensions
{
    public static IApplicationBuilder UseRequestTiming(
        this IApplicationBuilder app)
    {
        return app.UseMiddleware<RequestTimingMiddleware>();
    }
}

// Program.cs — how to wire it all up
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var app = builder.Build();

// Register exception handling FIRST so it wraps everything
app.UseExceptionHandler("/error");

// Our custom timing middleware — early so it times the full request
app.UseRequestTiming();

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

// Program.cs — demonstrating Use, Run, and Map in a single app

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// MAP: branch the pipeline for /health — nothing else runs for this path
app.Map("/health", healthApp =>
{
    // This Run only applies inside the /health branch
    healthApp.Run(async context =>
    {
        // Lightweight health check — no auth, no logging overhead
        context.Response.ContentType = "application/json";
        await context.Response.WriteAsync("{\"status\": \"healthy\"}");
    });
});

// USE: add a header to every response NOT handled by the /health branch
app.Use(async (context, next) =>
{
    // Runs on the way out — safe to set headers here before flush
    await next(context);
    context.Response.Headers.Append("X-Powered-By", "TheCodeForge");
});

// MAPWHEN: branch based on a condition — here, requests with a specific header
app.MapWhen(
    context => context.Request.Headers.ContainsKey("X-Internal-Request"),
    internalApp =>
    {
        internalApp.Run(async context =>
        {
            await context.Response.WriteAsync("Internal route — restricted access");
        });
    });

// RUN: terminal middleware for all remaining requests
// IMPORTANT: anything registered after this is NEVER reached
app.Run(async context =>
{
    await context.Response.WriteAsync("Main application response");
});

// This middleware is DEAD CODE — app.Run above is terminal
// The framework silently ignores it. Don't do this.
app.Use(async (context, next) =>
{
    Console.WriteLine("This never executes!");
    await next(context);
});

app.Run(); // starts the web server (different Run — on WebApplication, not IApplicationBuilder)

// Program.cs — the recommended middleware order for a production API
// Each comment explains WHY it's in this position, not just WHAT it does

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
builder.Services.AddControllers();

var app = builder.Build();

// 1. EXCEPTION HANDLER — outermost layer, catches exceptions from everything below
//    In development, use the developer exception page for stack traces instead
if (app.Environment.IsDevelopment())
    app.UseDeveloperExceptionPage();
else
    app.UseExceptionHandler("/error");

// 2. HSTS + HTTPS REDIRECTION — security headers before any content is served
app.UseHsts();
app.UseHttpsRedirection();

// 3. STATIC FILES — served before routing to avoid routing overhead for assets
//    Static files are terminal for matched paths — they never hit your controllers
app.UseStaticFiles();

// 4. ROUTING — parses the URL and selects the endpoint
//    Must come before UseAuthentication so endpoint metadata is available
//    (used by some auth handlers to check endpoint-level attributes)
app.UseRouting();

// 5. CORS — must come after UseRouting, before UseAuthentication
//    Preflight OPTIONS requests need CORS headers before auth checks
app.UseCors("AllowFrontend");

// 6. AUTHENTICATION — reads the token/cookie and builds the ClaimsPrincipal
//    MUST come before UseAuthorization
app.UseAuthentication();

// 7. AUTHORISATION — checks if the established identity has permission
//    Relies on UseAuthentication having already run
app.UseAuthorization();

// 8. ENDPOINT EXECUTION — actually runs your controller actions / minimal API handlers
app.MapControllers();

app.Run();