.NET Core Middleware Tutorial: Full Guide for Beginners | DotNetSchool

Step 1: Create an ASP.NET Core Web Application

First, let's create a new ASP.NET Core web application.

1. Open Visual Studio (or use .NET CLI).
2. Create a New Project.
   • Select ASP.NET Core Web App (Model-View-Controller) or any preferred template.
3. Configure the Project:
   • Name your project (e.g., MiddlewareDemo).
   • Choose the framework version (.NET 6 or later is recommended).

Step 2: Understanding Middleware

Middleware is software that's assembled into an app pipeline to handle requests and responses. Each middleware component can:

• Choose whether to pass the request to the next component in the pipeline.
• Perform work before the next middleware component in the pipeline.
• Perform work after the next middleware component responds.

Step 3: Configure Middleware in Startup.cs or Program.cs

In recent versions of ASP.NET Core (3.x and later), the configuration of middleware has moved to Program.cs. However, if you're using an older template, it might be in Startup.cs. Below, we will demonstrate using both approaches.

Using Program.cs (Recommended)

For .NET 6 and later:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

// Custom middleware
app.Use(async (context, next) =>
{
    await context.Response.WriteAsync("Middleware Start\n");
    await next(); // Passes control to the next middleware in the pipeline
    await context.Response.WriteAsync("Middleware End\n");
});

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Using Startup.cs

For .NET 5 and earlier:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllersWithViews();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        // Custom middleware
        app.Use(async (context, next) =>
        {
            await context.Response.WriteAsync("Middleware Start\n");
            await next(); // Passes control to the next middleware in the pipeline
            await context.Response.WriteAsync("Middleware End\n");
        });

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(
              name: "default",
              pattern: "{controller=Home}/{action=Index}/{id?}");
        });
    }
}

Step 4: Create Custom Middleware

We'll create a custom piece of middleware that sets a header on every HTTP response.

Define the Middleware

Create a file named ResponseHeaderMiddleware.cs:

using Microsoft.AspNetCore.Http;
using System.Threading.Tasks;

public class ResponseHeaderMiddleware
{
    private readonly RequestDelegate _next;

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

    public async Task InvokeAsync(HttpContext context)
    {
        context.Response.Headers["X-Custom-Header"] = "MiddlewarePipeline";

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

Register the Middleware

Add the middleware to the pipeline. This should happen between UseRouting() and UseEndpoints():

In Program.cs:

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.UseMiddleware<ResponseHeaderMiddleware>();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

In Startup.cs:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

    app.UseRouting();

    app.UseAuthorization();

    app.UseMiddleware<ResponseHeaderMiddleware>();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
          name: "default",
          pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}  

Step 5: Testing the Configuration

Run the application and navigate to the home page (e.g., https://localhost:PORT). Use browser developer tools (F12) or tools like Postman to inspect the HTTP response headers.

You should see an X-Custom-Header with the value MiddlewarePipeline.

Step 6: Adding Additional Built-In Middleware

The following middleware provides common functionalities such as handling errors, serving static files, routing, and authentication.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseRouting();

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

    app.UseMiddleware<ResponseHeaderMiddleware>(); 

    app.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");

    app.Run();
}

Step 7: Understanding the Order of Middleware

The order in which middleware components are added to the application pipeline is important because each middleware performs its operation in the order it was added.

1. Authentication: Verifies user credentials.
2. Authorization: Determines if a user has access to specific resources.
3. Request Logging: Logs data about incoming requests.
4. Static Files Service: Serves static files directly from the web root.
5. Routing Middleware: Determines which route should handle the incoming request.
6. Error Handling Middleware: Displays error pages when a request fails.
7. Custom Middleware: Any middleware specific to your application.
8. Endpoints Middleware: Maps the incoming request to endpoint handlers (MVC, Razor Pages, etc.).

Example: Adding Multiple Custom Middleware

Let's add two additional pieces of custom middleware:

Middleware 2: Log Request Method

Create a RequestMethodLoggerMiddleware.cs:

public class RequestMethodLoggerMiddleware
{
    private readonly RequestDelegate _next;

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

    public async Task InvokeAsync(HttpContext context)
    {
        var method = context.Request.Method;
        Console.WriteLine($"Request Method: {method}");
        await _next(context);
    }
}

Middleware 3: Set Response ContentType

Create a SetContentTypeMiddleware.cs:

public class SetContentTypeMiddleware
{
    private readonly RequestDelegate _next;

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

    public async Task InvokeAsync(HttpContext context)
    {
        context.Response.ContentType = "application/json";
        await _next(context);
    }
}

Registering the Middleware

Modify the Configure method in Program.cs or Startup.cs:

app.UseRouting();

app.UseAuthorization();

app.UseMiddleware<RequestMethodLoggerMiddleware>();
app.UseMiddleware<ResponseHeaderMiddleware>();
app.UseMiddleware<SetContentTypeMiddleware>();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Step 8: Verify Middleware Order

Run the application and make requests to it. You should observe that the custom middleware RequestMethodLoggerMiddleware, ResponseHeaderMiddleware, and SetContentTypeMiddleware each perform their actions in the specified order.

1. RequestMethodLoggerMiddleware logs the HTTP request method.
2. ResponseHeaderMiddleware adds the custom header.
3. SetContentTypeMiddleware sets the response content type to application/json.

Summary

By following these steps, you've learned how to configure the middleware pipeline in ASP.NET Core, including:

• Adding built-in middleware components.
• Creating and adding custom middleware components.
• Understanding the importance of the middleware order.