Middlewares in ASP.NET - A simple guide

Introduction

Think of ASP.NET Core like a high-speed assembly line for internet requests. Every time someone visits the site, their request travels through a series of "stations" called Middleware. At each station, the app can do a specific job, like checking if the user is logged in, logging data, or handling errors. These stations can even "stop" a request early if something is wrong—like a security guard blocking someone without a badge.

In this article, we'll explore how ASP.NET Core processes incoming requests i.e how middleware functions.

What are Middlewares

Middleware serves as the essential foundation for the ASP.NET Core request pipeline. It functions as a sequence of software components designed to process incoming HTTP requests and outgoing responses. Each piece of middleware has the power to inspect, adjust, or even stop a request before it ever hits the application's main logic. This setup provides a structured way to manage tasks like security, logging, and error handling.

As a request enters app, it travels through the pipeline in the specific order we have registered each component. Every middleware piece faces a choice: it can handle the request and hand it off to the next component, or it can generate a response on the spot. When a component stops a request from moving further, it "short-circuits" the pipeline—a perfect tactic for blocking unauthenticated users or delivering cached content instantly.

The beauty of this pipeline is its total flexibility. We can rely on built-in middleware for common needs like routing and authentication, or develop custom components for specialized tasks. Because these pieces run one after another, their order is vital. For example, authentication must always occur before authorization so the system knows who a user is before deciding what they can access.

Setting up this pipeline is straightforward in the Program.cs file, using simple methods like app.Use, app.Run, and app.Map. This organized approach ensures every request is handled predictably while giving the power to customize the entire journey.

How Middleware work

Every piece of middleware in the pipeline follows a consistent pattern- it receives the HttpContext, performs its specific task, and then either passes control to the next component or "short-circuits" the process by sending a response back immediately. When middleware short-circuits a request, it stops all remaining components from running, which is a great way to optimize performance by handling errors or serving cached data early.

By organizing these components correctly, we can efficiently manage security, logging, and data transformations. This structured approach ensures that every request flows through ASP.NET Core application in a smooth, fast, and predictable way.

The order of the middleware is critical. Components run sequentially as requests flow in and responses flow out.

Request Flow (Inbound): The request goes down the pipeline in the order we have register middleware (Top-Down).
Response Flow (Outbound): The response travels back up the pipeline in the reverse order (Bottom-Up) if await next() was called.

// Layer 1: The Receptionist (Logging)
app.Use(async (context, next) =>
{
    Console.WriteLine("Receptionist: Checking the visitor in...");
    await next(); // Allow the visitor to go to the next floor
    Console.WriteLine("Receptionist: Checking the visitor out...");
});

// Layer 2: Security Scanner (Authentication)
app.Use(async (context, next) =>
{
    Console.WriteLine("Scanner: Checking ID badge...");
    
    // Example of short-circuiting: 
    // If no ID is found, we stop them here and don't call next()
    if (!context.Request.Headers.ContainsKey("X-ID-Badge"))
    {
        context.Response.StatusCode = 401;
        await context.Response.WriteAsync("Access Denied: No Badge Found.");
        return; 
    }

    await next(); 
    Console.WriteLine("Scanner: Scanning bags on the way out...");
});

// Layer 3: The Office (The Final Destination)
app.Run(async (context) =>
{
    Console.WriteLine("Office: Doing the actual work...");
    await context.Response.WriteAsync("Welcome to the main office!");
});

Expected Execution Flow:

Receptionist: Checking the visitor in...
Scanner: Checking ID badge...
Office: Doing the actual work...
Scanner: Scanning bags on the way out...
Receptionist: Checking the visitor out...

Request Delegate & HttpContext:

Understanding the relationship between the Request Delegate and HttpContext is essential for mastering the ASP.NET Core pipeline.

The HttpContext (The Cargo)

Think of the HttpContext as a large envelope that contains everything about a single web request. It travels through the entire pipeline and carries:

Request: Information coming in (URL, Headers, Cookies, Form data).
Response: Information going out (Status code, Body, Headers).
User: Information about who is making the request.

The Request Delegate (The Worker)

A Request Delegate is a functional piece of code (specifically a RequestDelegate) that processes the HttpContext. It is the "worker" that looks at the envelope, does something with it, and passes it to the next worker.

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

// This function IS a Request Delegate
// It takes HttpContext as an input and returns a Task
RequestDelegate myWorker = async (HttpContext context) =>
{
    // Reading from the HttpContext (The Request)
    string? userAgent = context.Request.Headers.UserAgent;

    // Writing to the HttpContext (The Response)
    context.Response.StatusCode = 200;
    await context.Response.WriteAsync($"Our browser is: {userAgent}");
};

// Telling the app to use our worker for all requests
app.Run(myWorker);

app.Run();

Summary of the Relationship:

HttpContext is the data (the "what").
Request Delegate is the logic (the "how").

When a request hits the server, ASP.NET Core creates the HttpContext and hands it to the first Request Delegate in the pipeline.

Built-In Middlewares

ASP.NET Core remains a powerhouse for web development largely due to its robust library of pre-configured Middleware. These built-in components act as ready-made "checkpoints" that we can plug into our request pipeline to handle critical tasks like security, traffic routing, and error management without writing custom code from scratch.

Exception Handling Middleware

Captures unhandled crashes and provides a centralized way to log errors and return custom error responses.

app.UseExceptionHandler("/Error");

Routing Middleware

Analyzes the incoming URL to determine which endpoint (like a Controller or Minimal API) should handle the request.

app.UseRouting();

Authentication and Authorization Middleware

These work together to secure the app: UseAuthentication identifies the user, while UseAuthorization checks their permissions.

app.UseAuthentication();

app.UseAuthorization();

Static Files Middleware

Efficiently serves assets like images, CSS, and JavaScript directly from the wwwroot folder.

app.UseStaticFiles();

CORS Middleware

Cross-Origin Resource Sharing (CORS) manages which external domains are permitted to access the API.

app.UseCors(p => p.WithOrigins("https://trusted.com").AllowAnyMethod());

Response Compression Middleware

Reduces bandwidth usage by shrinking responses before they are sent to the client, improving performance.

app.UseResponseCompression();

Session Middleware

Enables the application to store and retrieve user-specific data during their visit using in-memory or distributed caches.

app.UseSession();

HTTPS Redirection Middleware

Secures communication by automatically forcing all incoming HTTP requests to use the encrypted HTTPS protocol.

app.UseHttpsRedirection();

Request Logging Middleware

Records details about every HTTP request, which is essential for debugging, monitoring, and security audits.

app.UseSerilogRequestLogging();

Endpoint Middleware

The final stage where the request is dispatched to its intended target, such as a Controller or Razor Page.

app.MapControllers();

The order of registration is critical. For example, we must always call UseRouting before UseAuthorization so the app knows which resource is being accessed before checking if the user has permission to see it.

Custom Middleware

This remains one of the most powerful ways to extend our application's capabilities. While the built-in tools cover the basics, creating our own middleware allows us to inject specialized logic—like custom security headers, niche logging, or unique business rules—directly into the heart of the request pipeline. We will look into it more detail in another article, lets focus on in-built ones in this article.

How to create and stop Middleware pipeline

Request Delegate based Middleware remains the most straightforward method for injecting custom logic into the pipeline. This approach uses inline delegates, allowing us to define middleware directly within Program.cs file without the overhead of creating separate classes.

This method is perfect for quick tasks like specialized logging, adding custom headers, or simple performance timing.

// Simple monitoring middleware
app.Use(async (context, next) =>
{
    // Logic before the next component runs
    Console.WriteLine($"Incoming: {context.Request.Method} {context.Request.Path}");

    await next(); // Hand control to the next middleware in line

    // Logic after the rest of the app has finished
    Console.WriteLine($"Outgoing: Status {context.Response.StatusCode}");
});

Short-Circuiting is a vital performance and security tactic in ASP.NET Core. It occurs when a middleware component generates a response and decides not to call the next middleware in the pipeline. This effectively stops the request from traveling any further, preventing unnecessary processing in controllers or database.

In this example, the middleware checks a "Maintenance Mode" flag. If active, it short-circuits the pipeline and tells the user to come back later, protecting the rest of the app during updates.

bool isMaintenanceMode = true;

app.Use(async (context, next) =>
{
    if (isMaintenanceMode)
    {
        // 1. Set the response status
        context.Response.StatusCode = 503; // Service Unavailable
        
        // 2. Send the message
        await context.Response.WriteAsync("Site is down for maintenance. Please try again later.");
        
        // 3. IMPORTANT: We do NOT call 'await next()'. 
        // This short-circuits the pipeline here.
        return;
    }

    // If not in maintenance, continue as normal
    await next();
});

app.MapGet("/", () => "Welcome to the App!");

Best Practices

Middleware remains a cornerstone for processing traffic in ASP.NET Core Web APIs. Properly designing and organizing the pipeline is essential for ensuring high performance, long-term maintainability, and robust security.

1. Order is Everything

Middleware executes in the exact sequence it is registered in Program.cs. Always place Exception Handling first to catch all downstream errors, followed by Routing, then Authentication, and finally Authorization. Getting this wrong can lead to security holes or unhandled crashes.

2. Keep Middleware "Lean"

Middleware should be fast and focused on a single task (like logging or security). Avoid putting heavy business logic or long-running database queries inside a middleware component. If it takes too long to process, it slows down every single request entering the application.

3. Use Short-Circuiting Wisely

Stop the request as early as possible if it doesn't meet requirements. For example, if an API Key is missing, return a 401 Unauthorized immediately. This prevents the request from hitting expensive resources like database or external services.

4. Avoid "Fat" Program.cs Files

For complex logic, move the middleware into a separate Middleware Class rather than using long inline lambda expressions. This keeps the startup code clean and makes the custom logic much easier to unit test.

5. Use Built-in Middleware First

Before writing a custom solution, check if a built-in component exists. ASP.NET Core provides highly optimized middleware for CORS, Compression, Caching, and Rate Limiting. These are maintained by Microsoft and are typically more performant and secure than custom-built alternatives.

Here is the professional standard for arranging the middleware to ensure every request is handled efficiently:

var app = builder.Build();

// 1. Global Exception Handling - Catch all errors from the very start
app.UseExceptionHandler("/error");      

// 2. HTTPS Redirection - Secure the connection before processing data
app.UseHttpsRedirection();              

// 3. Routing Middleware - Determine where the request is trying to go
app.UseRouting();                       

// 4. CORS Middleware - Validate cross-origin access early
app.UseCors();                           

// 5. Authentication - Identify WHO the user is
app.UseAuthentication();                 

// 6. Authorization - Confirm WHAT the user can do
app.UseAuthorization();                  

// 7. Custom Middleware - Niche logic (e.g., specialized logging or headers)
app.UseMiddleware<CustomMiddleware>();   

// 8. Endpoint Execution - Finally execute the controller or minimal API logic
app.MapControllers();

app.Run();

Why this specific order is best:

Safety First: Placing Exception Handling at the very top ensures that if any later middleware (like Database or Custom logic) crashes, the error is caught and handled gracefully.
Efficiency: By placing CORS and Authentication before the custom logic, we can reject unauthorized or untrusted requests before the server wastes any time processing them.
Logic Flow: We must call Routing before Authorization because the system needs to know which "room" the user is trying to enter before it can check if they have the specific key for it.

Conclusion

In this article we have seen how Middleware remains the essential foundation of the ASP.NET Core request pipeline, providing a structured way to manage global tasks like security, logging, and error handling. By mastering the way these components function and strictly following the correct execution order, we can ensure Web APIs are built for high performance, maximum security, and long-term maintainability. Hope this helps.