Minimal APIs and Middleware in ASP.NET Core

Minimal APIs and Middleware in ASP.NET Core Introduction ASP.NET Core Minimal APIs let you build simple and fast web APIs with less code. Middleware helps process requests and responses, adding features like logging, authentication, and error handling. In this guide, you'll learn how to set up a Minimal API and use middleware effectively. A Short History of Middleware Middleware has been used in web applications for a long time. In the past, web apps handled requests in one big block of code. Over time, middleware was introduced to make request handling more modular and flexible. Classic ASP & Early .NET: Used HTTP modules and handlers. ASP.NET MVC & Web API (2010s): Introduced delegating handlers for request processing. ASP.NET Core (2016): Introduced a fully modular middleware pipeline. ASP.NET Core Minimal APIs (2021+): Made middleware even simpler and lighter. Setting Up a Minimal API Prerequisites Make sure you have .NET 8 SDK installed. Check by running: dotnet --version Creating a Minimal API Project Run these commands: dotnet new web -o MinimalApiDemo cd MinimalApiDemo Open Program.cs and you'll see this simple API: var builder = WebApplication.CreateBuilder(args); var app = builder.Build(); app.MapGet("/", () => "Hello, World!"); app.Run(); Run the app: dotnet run Go to http://localhost:5000 in your browser to see the response What is Middleware? Middleware is a set of steps that process each request and response. It can: Handle authentication and security Log requests Control CORS settings Manage errors Example of simple logging middleware: app.Use(async (context, next) => { Console.WriteLine($"Request: {context.Request.Method} {context.Request.Path}"); await next(); Console.WriteLine($"Response: {context.Response.StatusCode}"); }); Creating Custom Middleware Instead of writing middleware inside Program.cs, we can create a separate class. Example: Logging Middleware Create LoggingMiddleware.cs: public class LoggingMiddleware { private readonly RequestDelegate _next; public LoggingMiddleware(RequestDelegate next) { _next = next; } public async Task Invoke(HttpContext context) { Console.WriteLine($"Incoming: {context.Request.Method} {context.Request.Path}"); await _next(context); Console.WriteLine($"Outgoing: {context.Response.StatusCode}"); } } Register it in Program.cs: app.UseMiddleware(); Handling Errors with Middleware To catch errors globally, add this middleware: app.Use(async (context, next) => { try { await next(); } catch (Exception ex) { context.Response.StatusCode = 500; await context.Response.WriteAsync($"Error: {ex.Message}"); } }); Adding Authentication Middleware To use JWT authentication, install the package: dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer Set it up in Program.cs: builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = "https://your-auth-server.com"; options.Audience = "your-api-audience"; }); app.UseAuthentication(); app.UseAuthorization(); app.MapGet("/secure", () => "Secure data").RequireAuthorization(); Advanced Example: Rate Limiting Middleware using Microsoft.AspNetCore.RateLimiting; using System.Threading.RateLimiting; var builder = WebApplication.CreateBuilder(args); builder.Services.AddRateLimiter(_ => _ .AddFixedWindowLimiter(policyName: "fixed", options => { options.PermitLimit = 4; options.Window = TimeSpan.FromSeconds(12); options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst; options.QueueLimit = 2; })); var app = builder.Build(); app.UseRateLimiter(); static string GetTicks() => (DateTime.Now.Ticks & 0x11111).ToString("00000"); app.MapGet("/", () => Results.Ok($"Hello {GetTicks()}")) .RequireRateLimiting("fixed"); app.Run(); Best Practices for Middleware Order matters: Middleware runs in the order you add it. Handle errors properly: Always catch unexpected errors. Keep it simple: Middleware should be lightweight. Use dependency injection: Avoid static classes for middleware. Conclusion Minimal APIs in ASP.NET Core make it easy to build lightweight web applications. Middleware helps you add features like logging, security, and error handling in a clean and reusable way. Try creating your own middleware for caching, validation, or performance monitoring! References Minimal APIs in ASP.NET Core ASP.NET Core Middleware Error Handling in ASP.NET Core Authentication in ASP.NET Core Rate Limiting Middleware

Mar 13, 2025 - 10:06

Minimal APIs and Middleware in ASP.NET Core

Introduction

ASP.NET Core Minimal APIs let you build simple and fast web APIs with less code. Middleware helps process requests and responses, adding features like logging, authentication, and error handling.

In this guide, you'll learn how to set up a Minimal API and use middleware effectively.

A Short History of Middleware

Middleware has been used in web applications for a long time. In the past, web apps handled requests in one big block of code. Over time, middleware was introduced to make request handling more modular and flexible.

Classic ASP & Early .NET: Used HTTP modules and handlers.
ASP.NET MVC & Web API (2010s): Introduced delegating handlers for request processing.
ASP.NET Core (2016): Introduced a fully modular middleware pipeline.
ASP.NET Core Minimal APIs (2021+): Made middleware even simpler and lighter.

Setting Up a Minimal API
Prerequisites
Make sure you have .NET 8 SDK installed. Check by running:

dotnet --version

Creating a Minimal API Project

Run these commands:

dotnet new web -o MinimalApiDemo cd MinimalApiDemo

Open Program.cs and you'll see this simple API:

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

app.MapGet("/", () => "Hello, World!");

app.Run();

Run the app:

dotnet run

Go to http://localhost:5000 in your browser to see the response

What is Middleware?

Middleware is a set of steps that process each request and response. It can:

Handle authentication and security
Log requests
Control CORS settings
Manage errors

Example of simple logging middleware:

app.Use(async (context, next) =>
{
    Console.WriteLine($"Request: {context.Request.Method} {context.Request.Path}");
    await next();
    Console.WriteLine($"Response: {context.Response.StatusCode}");
});

Creating Custom Middleware

Instead of writing middleware inside Program.cs, we can create a separate class.

Example: Logging Middleware

Create LoggingMiddleware.cs:

public class LoggingMiddleware
{
    private readonly RequestDelegate _next;

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

    public async Task Invoke(HttpContext context)
    {
        Console.WriteLine($"Incoming: {context.Request.Method} {context.Request.Path}");
        await _next(context);
        Console.WriteLine($"Outgoing: {context.Response.StatusCode}");
    }
}

app.UseMiddleware();

Handling Errors with Middleware

To catch errors globally, add this middleware:

app.Use(async (context, next) =>
{
    try
    {
        await next();
    }
    catch (Exception ex)
    {
        context.Response.StatusCode = 500;
        await context.Response.WriteAsync($"Error: {ex.Message}");
    }
});

Adding Authentication Middleware

To use JWT authentication, install the package:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Set it up in Program.cs:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://your-auth-server.com";
        options.Audience = "your-api-audience";
    });

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

app.MapGet("/secure", () => "Secure data").RequireAuthorization();

Advanced Example: Rate Limiting Middleware

using Microsoft.AspNetCore.RateLimiting;
using System.Threading.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRateLimiter(_ => _
    .AddFixedWindowLimiter(policyName: "fixed", options =>
    {
        options.PermitLimit = 4;
        options.Window = TimeSpan.FromSeconds(12);
        options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        options.QueueLimit = 2;
    }));

var app = builder.Build();

app.UseRateLimiter();

static string GetTicks() => (DateTime.Now.Ticks & 0x11111).ToString("00000");

app.MapGet("/", () => Results.Ok($"Hello {GetTicks()}"))
                           .RequireRateLimiting("fixed");

app.Run();

Best Practices for Middleware

Order matters: Middleware runs in the order you add it.
Handle errors properly: Always catch unexpected errors.
Keep it simple: Middleware should be lightweight.
Use dependency injection: Avoid static classes for middleware.

Conclusion

Minimal APIs in ASP.NET Core make it easy to build lightweight web applications. Middleware helps you add features like logging, security, and error handling in a clean and reusable way.

Try creating your own middleware for caching, validation, or performance monitoring!

References

Minimal APIs in ASP.NET Core
ASP.NET Core Middleware
Error Handling in ASP.NET Core
Authentication in ASP.NET Core
Rate Limiting Middleware