Implementing Custom Middleware in ASP.NET Core: A Comprehensive Guide

Date- Mar 24,2026

aspnetcore middleware

Overview

Custom middleware in ASP.NET Core refers to components that are assembled into an application pipeline to handle requests and responses. Each middleware component can perform operations on the incoming request, the outgoing response, or both, allowing developers to insert their own processing logic at various stages of the request lifecycle. This modular architecture is crucial for handling cross-cutting concerns such as logging, authentication, error handling, and response formatting.

The existence of middleware in ASP.NET Core addresses the need for a flexible and maintainable way to manage request and response processing. Instead of tightly coupling these concerns within controllers or services, middleware allows for a separation of concerns, which leads to cleaner code and improved testability. For example, a custom logging middleware can be added to track all incoming requests without modifying the request handling logic in controllers.

Real-world use cases for custom middleware include implementing authentication and authorization checks, logging request data for analytics, handling CORS (Cross-Origin Resource Sharing), managing session state, and transforming responses before they reach the client. This capability allows developers to tailor the ASP.NET Core pipeline to fit specific application requirements, enhancing both functionality and performance.

Prerequisites

ASP.NET Core: Understanding the ASP.NET Core framework and its pipeline architecture.
C#: Proficiency in C# programming language as middleware is developed using it.
Visual Studio: Familiarity with the Visual Studio IDE for creating and running ASP.NET Core applications.
Basic Web Concepts: Understanding HTTP requests and responses, as middleware operates at this level.

Creating a Basic Custom Middleware

To create a custom middleware in ASP.NET Core, you need to define a class that contains a method called Invoke or InvokeAsync. This method will contain the logic for processing the request. The middleware must also accept a RequestDelegate parameter, which represents the next middleware in the pipeline. After executing its logic, the middleware should call this delegate to pass control to the next component.

public class CustomMiddleware
{
    private readonly RequestDelegate _next;

    public CustomMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Logic before the next middleware
        await context.Response.WriteAsync("Before middleware\n");

        // Call the next middleware in the pipeline
        await _next(context);

        // Logic after the next middleware
        await context.Response.WriteAsync("After middleware\n");
    }
}

In this code, the CustomMiddleware class is defined with a constructor that takes a RequestDelegate parameter. The InvokeAsync method is where the middleware logic is executed. Before calling the next middleware using await _next(context);, a message "Before middleware\n" is written to the response. After the next middleware completes, another message "After middleware\n" is added to the response.

The expected output when this middleware is executed in the pipeline will be the two messages added before and after the invocation of the next middleware.

Registering the Middleware

To use the custom middleware, it must be registered in the Startup.cs file within the Configure method. Middleware is added to the pipeline in a specific order, so the position of registration affects the behavior of the application.

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseMiddleware();
        app.Run(async context => {
            await context.Response.WriteAsync("Hello from the final middleware!\n");
        });
    }
}

In this example, the CustomMiddleware is registered using app.UseMiddleware<CustomMiddleware>();. After the custom middleware, a final middleware writes a message to the response. The order of middleware registration is crucial as it determines the flow of request and response processing.

Use Cases for Custom Middleware

Custom middleware can be used to implement a variety of functionalities that are essential for web applications. Common use cases include logging, authentication, and error handling. By creating middleware for these concerns, developers can avoid duplicating code across controllers and services.

Logging Middleware Example

Logging requests and responses is a common requirement in web applications. A custom logging middleware can capture this information for analytics and debugging purposes.

public class LoggingMiddleware
{
    private readonly RequestDelegate _next;

    public LoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Log request information
        Console.WriteLine($"Request: {context.Request.Method} {context.Request.Path}");

        // Call the next middleware
        await _next(context);

        // Log response information
        Console.WriteLine($"Response: {context.Response.StatusCode}");
    }
}

The LoggingMiddleware captures the HTTP method and path of the incoming request and logs it to the console. After calling the next middleware, it logs the HTTP status code of the response. This information can be invaluable for monitoring the application’s behavior and diagnosing issues.

Authentication Middleware Example

Implementing authentication can also be accomplished through custom middleware. This middleware can check for valid tokens before allowing access to protected resources.

public class AuthenticationMiddleware
{
    private readonly RequestDelegate _next;

    public AuthenticationMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Check for an authentication token
        if (!context.Request.Headers.ContainsKey("Authorization"))
        {
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await context.Response.WriteAsync("Unauthorized\n");
            return;
        }

        // Call the next middleware
        await _next(context);
    }
}

This AuthenticationMiddleware checks for an "Authorization" header in the request. If it is absent, it responds with a 401 Unauthorized status and terminates the request. If present, it allows the request to proceed to the next middleware.

Edge Cases & Gotchas

When implementing custom middleware, there are several pitfalls developers should be aware of. One common mistake is failing to call the next middleware in the pipeline. If the RequestDelegate is not invoked, the request will not be processed further, leading to incomplete responses.

public class IncorrectMiddleware
{
    private readonly RequestDelegate _next;

    public IncorrectMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Missing next middleware call
        await context.Response.WriteAsync("This is an incorrect middleware\n");
        // await _next(context); // This line is missing
    }
}

In the above code, the middleware fails to call await _next(context);, resulting in the termination of the request pipeline, which can cause the application to hang or return incomplete responses.

Performance & Best Practices

To ensure optimal performance when implementing custom middleware, developers should adhere to best practices. Avoid blocking calls in middleware to maintain the asynchronous nature of ASP.NET Core. Instead, utilize asynchronous programming patterns to prevent thread pool exhaustion. For example, when performing I/O operations, ensure to use async/await patterns.

public class AsyncMiddleware
{
    private readonly RequestDelegate _next;

    public AsyncMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Simulate an asynchronous operation
        await Task.Delay(100); // Asynchronous delay

        await _next(context);
    }
}

This AsyncMiddleware demonstrates the use of asynchronous delay to simulate a non-blocking operation. By using async/await, it ensures that the request processing does not block the thread, allowing for better scalability.

Real-World Scenario: Building a Mini-Project

To illustrate the concepts of custom middleware, let's create a simple ASP.NET Core application that implements logging and authentication middleware. This mini-project will demonstrate how to tie everything together.

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseMiddleware();
        app.UseMiddleware();
        app.Run(async context => {
            await context.Response.WriteAsync("Hello, authenticated user!\n");
        });
    }
}

In this application, both the LoggingMiddleware and AuthenticationMiddleware are registered in the pipeline. The application responds with a message only if the request passes through both middlewares successfully. The logging middleware will log the request details, while the authentication middleware will check for the authorization token.

Conclusion

Custom middleware is essential for handling cross-cutting concerns in ASP.NET Core applications.
Middleware allows for a modular approach to request processing, enhancing maintainability and scalability.
Best practices include ensuring asynchronous operations and avoiding common pitfalls like skipping the next middleware call.
Real-world applications benefit from custom middleware for logging, authentication, and more.
Familiarity with middleware design patterns can greatly improve your ASP.NET Core development skills.