---
title: 'C# Interview Guide: ASP.NET Core Middleware Pipeline'
excerpt: >-
Comprehensive guide on ASP.NET Core Middleware Pipeline including pipeline mechanics, proper ordering, custom middleware creation with DI best practices, detailed flow diagrams, sequence interactions, and observability recommendations.
tags:
- aspnet-core
- middleware
- csharp
- dotnet
- software-architecture
seoTitle: 'C# ASP.NET Core Middleware Pipeline Explained with Diagrams & Code'
seoDescription: >-
Deep dive into ASP.NET Core Middleware Pipeline with architecture diagrams, custom middleware examples, ordering best practices, and observability patterns.
category: tech-stacks
---
## Q6 — Explain the ASP.NET Core Middleware Pipeline and Write Custom Middleware
*Level: Mid-Level | Topic: ASP.NET Core*
---
### How the Middleware Pipeline Works: Fundamentals and Architecture
ASP.NET Core's request processing is built around a **middleware pipeline** — a linear, ordered chain of components that each have the opportunity to process HTTP requests and responses.
Each middleware in the pipeline:
- Receives the `HttpContext` for the current request.
- Can perform logic before invoking the next middleware.
- Calls `await next(context)` to pass control downstream.
- Optionally modifies the response after the downstream middleware has executed.
This chaining allows for cross-cutting concerns — such as logging, authentication, or error handling — to be modular and composable.
> <mark class="hl-amber">The pipeline is bidirectional: requests flow “down” the pipeline towards the terminal endpoint, and responses flow “up” the pipeline as each middleware’s awaiting call returns.</mark>
Middleware forms a logical stack: outer middleware wraps the inner ones, establishing an execution context unwinding pattern similar to synchronous call stacks.
```mermaid
flowchart LR
A[HTTP Request] --> M1[Middleware 1<br/>Logging, Exception Handling]
M1 --> M2[Middleware 2<br/>Authentication]
M2 --> M3[Middleware 3<br/>Authorization]
M3 --> M4[Middleware 4<br/>Routing & Endpoint]
M4 --> E[Terminal Request Handler]
E --> M4
M4 --> M3
M3 --> M2
M2 --> M1
M1 --> R[HTTP Response]
Figure: High-level HTTP request/response flow through middleware pipeline.
Why Ordering of Middleware Matters
The order you register middleware in Program.cs directly affects runtime behavior and security:
| Middleware | Recommended Position | Reason |
|---|---|---|
| Exception Handling | First middleware in pipeline | To catch all downstream exceptions |
| Correlation & Logging | Early in pipeline | To tag and trace all requests |
| HTTPS Redirection | Before routing | Enforce secure connection early |
| CORS | Before authentication | Preflight requests must be answered first |
| Authentication | Before authorization | Need identity prematurely populated |
| Authorization | After authentication | Depends on authenticated identity |
| Rate Limiter | Close to endpoints | Protect endpoints from abuse |
| Routing/Endpoints | Last middleware | Terminal handling of requests |
Typical Registration Order in Program.cs
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
// Exception handling wraps entire pipeline.
app.UseExceptionHandler("/error");
// Assign correlation IDs to all requests for tracing.
app.UseCorrelationId();
// Redirect HTTP to HTTPS.
app.UseHttpsRedirection();
// Handle Cross-Origin Resource Sharing early.
app.UseCors();
// Authentication populates ClaimsPrincipal.
app.UseAuthentication();
// Authorization checks permissions.
app.UseAuthorization();
// Rate limiting to protect downstream APIs.
app.UseRateLimiter();
// Map controller endpoints.
app.MapControllers();
app.Run();
Custom Middleware: Implementing a Correlation ID Tracker
Correlation IDs are crucial for distributed request tracing. This middleware inspects input headers for a correlation ID or generates one, then attaches it to both request context and response.
// CorrelationIdMiddleware.cs — production-ready example
public sealed class CorrelationIdMiddleware
{
private const string HeaderName = "X-Correlation-Id";
private readonly RequestDelegate _next;
private readonly ILogger<CorrelationIdMiddleware> _logger;
public CorrelationIdMiddleware(RequestDelegate next,
ILogger<CorrelationIdMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
string correlationId = context.Request.Headers[HeaderName].FirstOrDefault()
?? Guid.NewGuid().ToString("N");
// Propagate correlation ID for downstream consumers.
context.Response.Headers[HeaderName] = correlationId;
context.Items["CorrelationId"] = correlationId;
// Logging scope enriches logs with correlation ID.
using (_logger.BeginScope(new { CorrelationId = correlationId }))
{
_logger.LogInformation("Processing {Method} {Path}",
context.Request.Method, context.Request.Path);
await _next(context);
}
}
}
// Clean extension method for easy registration.
public static class MiddlewareExtensions
{
public static IApplicationBuilder UseCorrelationId(
this IApplicationBuilder app)
=> app.UseMiddleware<CorrelationIdMiddleware>();
}
This middleware demonstrates key patterns: header inspection, response header modification, context item storage, logging scopes, and proper invocation of the next delegate.
Minimal Middleware Example: Request Timer
public class RequestTimingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<RequestTimingMiddleware> _logger;
public RequestTimingMiddleware(RequestDelegate next,
ILogger<RequestTimingMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
var watch = Stopwatch.StartNew();
await _next(context);
watch.Stop();
_logger.LogInformation("Request {Method} {Path} took {ElapsedMilliseconds}ms",
context.Request.Method, context.Request.Path, watch.ElapsedMilliseconds);
}
}
Simple timing middleware shows request measurement by starting stopwatch before and stopping after downstream completes.
Advanced: Using IMiddleware for Scoped Dependencies
Implementing middleware via IMiddleware enables constructor dependency injection with scoped services, better aligning to DI lifetimes and testability.
public class ScopedLoggingMiddleware : IMiddleware
{
private readonly ILogger<ScopedLoggingMiddleware> _logger;
public ScopedLoggingMiddleware(ILogger<ScopedLoggingMiddleware> logger)
{
_logger = logger;
}
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
_logger.LogInformation("Scoped middleware executing");
await next(context);
}
}
// Registration in Program.cs
builder.Services.AddScoped<ScopedLoggingMiddleware>();
app.UseMiddleware<ScopedLoggingMiddleware>();
Note the constructor DI and separate interface, a better pattern for middleware requiring scoped or transient dependencies.
Pipeline Interaction Sequence Diagram
sequenceDiagram
participant Client
participant Middleware1 as ExceptionHandling
participant Middleware2 as CorrelationId
participant Middleware3 as Authentication
participant Middleware4 as Authorization
participant EndpointHandler as Controller
Client->>Middleware1: HTTP Request
Middleware1->>Middleware2: invoke next
Middleware2->>Middleware3: invoke next
Middleware3->>Middleware4: invoke next
Middleware4->>EndpointHandler: invoke next
EndpointHandler-->>Middleware4: Response
Middleware4-->>Middleware3: return
Middleware3-->>Middleware2: return
Middleware2-->>Middleware1: return (add header)
Middleware1-->>Client: HTTP ResponseFigure: Middleware request/response invocation sequence demonstrating control flow.
Middleware Pipeline Trade-offs and Best Practices
| Aspect | Middleware Approach | Endpoint Filters (ASP.NET Core 7+) |
|---|---|---|
| Scope | Runs globally to all requests | Runs near endpoint — more targeted |
| Dependency Injection | Supports scoped/transient via IMiddleware | Supports DI, lighter weight |
| Performance | Adds overhead per middleware component | Less overhead, optimized for minimal logic |
| Use Cases | Cross-cutting concerns (logging, auth, error handling) | Minimal response/request transformation |
| Complexity | Can become complicated with many middleware layers | Simpler, easier to reason about |
Use endpoint filters for lightweight concerns close to route handlers; prefer middleware for cross-cutting, global concerns requiring full pipeline access.
Observability: Logging, Metrics, and Tracing in Middleware Pipelines
Middleware is an excellent place to inject observability signals:
What to Log from Middleware
- Incoming request method, path, and correlation ID.
- Request and response headers if sensitive info is not exposed.
- Processing duration.
- Any exceptions caught.
- Identity information (user ID, roles).
- Rate limiting triggers.
Structured Log Example
{
"timestamp": "2024-06-19T15:25:47.000Z",
"level": "Information",
"message": "Request GET /api/orders",
"correlationId": "abc123xyz",
"userId": "user-789",
"durationMs": 47
}
Key Metrics to Emit (Use RED and USE frameworks)
| Metric Name | Type | Description | Unit |
|---|---|---|---|
| http_requests_total | Counter | Total number of requests | Count |
| http_requests_duration_ms | Histogram | Request latencies | Millis |
| http_requests_errors_total | Counter | Number of failed requests | Count |
| cpu_usage | Gauge | CPU utilization | % |
| memory_usage_bytes | Gauge | Memory consumption | Bytes |
| thread_pool_queue_length | Gauge | .NET thread pool queue size | Count |
Distributed Tracing with OpenTelemetry
Integrate OpenTelemetry to trace requests end-to-end:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetryTracing(tracerProviderBuilder =>
{
tracerProviderBuilder
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddJaegerExporter(); // Or your preferred exporter
});
var app = builder.Build();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();
SLI/SLO Table for Middleware Pipeline
| Service Level Indicator (SLI) | Target (SLO) | Rationale |
|---|---|---|
| Request success rate | ≥ 99.9% (HTTP 2xx/3xx) | High reliability expected |
| Request latency (p99) | ≤ 500ms | Maintain responsive user experience |
| Error rate (HTTP 5xx) | ≤ 0.1% | Low rate of server errors |
| Correlation ID presence | 100% | Essential for traceability |
| Traces generated per request | 100% | Full observability coverage |
Alerts Worth Paging
- High request error rate (>0.5% over 5 mins)
- Exception middleware catching unhandled exceptions
- Middleware latency anomalies (p99 latency > 1s)
- Missing correlation ID header on inbound requests
- Authentication failures exceeding threshold
- Rate limiter saturating frequently
Summary
- ASP.NET Core middleware is a powerful linear pipeline allowing modular request processing.
- Ordering is critical — exception handling first, auth before authorization.
- Writing custom middleware requires calling
await _next(context)to forward requests. - Use
IMiddlewareinterface for proper scoped DI handling. - Consider endpoint filters for lightweight concerns in .NET 7+.
- Add comprehensive observability with structured logging, metrics, and distributed tracing.
- Understand middleware impact on request flow via diagrams and sequence charts.
Mastering the middleware pipeline is essential for robust, secure, and observable ASP.NET Core application architectures.
Further Reading
- Microsoft Docs: Middleware
- Microsoft Docs: Dependency Injection in ASP.NET Core
- OpenTelemetry .NET SDK
Internal Mechanics of the ASP.NET Core Middleware Pipeline
Understanding the internal workings of ASP.NET Core’s middleware pipeline clarifies why ordering matters and how performance characteristics emerge.
Pipeline Construction: The RequestDelegate Chain
At startup, ASP.NET Core composes the middleware pipeline into a single delegate of type RequestDelegate:
public delegate Task RequestDelegate(HttpContext context);
Each middleware wraps the next by producing a delegate that calls its logic before or after invoking the downstream delegate:
RequestDelegate nextMiddleware = ...; // The next middleware in chain
RequestDelegate composed = async (ctx) =>
{
// Pre-processing logic
await nextMiddleware(ctx); // Downstream call
// Post-processing logic
};
This pattern continues until the terminal delegate is reached (typically endpoint routing or MVC controller action handler). The framework performs this composition during app.Build() (called implicitly by app.Run()).
flowchart TD
M1["Middleware1: RequestDelegate"]
M2["Middleware2: RequestDelegate"]
M3["Middleware3: RequestDelegate"]
E["Endpoint: RequestDelegate"]
M1 --> M2
M2 --> M3
M3 --> EBecause each middleware returns a Task, the pipeline forms an asynchronous call stack where the response “flows back” as these tasks complete.
Middleware Lifetime and Thread-Safety
- Each middleware class registered by
app.UseMiddleware<T>()is instantiated once per application lifetime (singleton-like behavior). - This means middleware must be thread-safe and stateless or store per-request state in
HttpContext.Items. - Using the
IMiddlewareinterface combined with DI container registrations allows middleware dependencies with scoped or transient lifetimes.
RequestContext and ExecutionFlow
HttpContext is an object supplied per request that holds all request metadata (headers, path, user, items dictionary, response, etc.) Middleware components interact exclusively via this context.
The core execution model is:
stateDiagram-v2
[*] --> Start
Start --> PreProcessing
PreProcessing --> AwaitNext: call next(context)
AwaitNext --> PostProcessing
PostProcessing --> [*]- Pre-processing is before calling
next(context) - Post-processing is after the awaited downstream completes
This allows middleware to wrap and catch exceptions, manipulate response streams, or measure latency precisely.
Exception Handling Internals in Middleware
Exception handling middleware wraps the rest of the pipeline in a try-catch block:
public async Task InvokeAsync(HttpContext context)
{
try
{
await _next(context);
}
catch (Exception ex)
{
// Log exception, write error response, etc.
}
}
This behavior is critical to prevent unhandled exceptions crashing the web server and to provide consistent response formats for errors.
Production Scenario: Implementing a Fail-Safe Logging Middleware with Retries
Consider a high-scale e-commerce ASP.NET Core app with a remote logging service that sometimes responds slowly or drops logs. You want to build middleware that:
- Adds correlation IDs for tracing
- Asynchronously sends logs to external service reliably
- Retries log sending on transient failures up to 3 times
- Measures request latency precisely, including retries
- Fails gracefully (no impact on user requests)
- Emits detailed metrics for observability
Step 1: Correlation ID Middleware
Leverage the earlier CorrelationIdMiddleware as a foundation, ensuring correlation ID propagation.
Step 2: Asynchronous Logging Middleware with Retries
public class ReliableLoggingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<ReliableLoggingMiddleware> _logger;
private readonly IHttpClientFactory _httpClientFactory;
private readonly int _maxRetries = 3;
public ReliableLoggingMiddleware(RequestDelegate next,
ILogger<ReliableLoggingMiddleware> logger,
IHttpClientFactory httpClientFactory)
{
_next = next;
_logger = logger;
_httpClientFactory = httpClientFactory;
}
public async Task InvokeAsync(HttpContext context)
{
var correlationId = (string?)context.Items["CorrelationId"] ?? Guid.NewGuid().ToString("N");
var method = context.Request.Method;
var path = context.Request.Path;
var stopwatch = Stopwatch.StartNew();
await _next(context);
stopwatch.Stop();
var logEntry = new
{
CorrelationId = correlationId,
Method = method,
Path = path,
StatusCode = context.Response.StatusCode,
DurationMs = stopwatch.ElapsedMilliseconds,
TimestampUtc = DateTime.UtcNow
};
var httpClient = _httpClientFactory.CreateClient("LoggingService");
var logContent = new StringContent(JsonSerializer.Serialize(logEntry),
Encoding.UTF8, "application/json");
int attempt = 0;
while (true)
{
try
{
attempt++;
var resp = await httpClient.PostAsync("/api/logs", logContent);
if (resp.IsSuccessStatusCode)
{
_logger.LogInformation("Logged request {Method} {Path} in {Duration}ms on attempt {Attempt}",
method, path, stopwatch.ElapsedMilliseconds, attempt);
break;
}
_logger.LogWarning("Failed to send log attempt {Attempt}: {StatusCode}",
attempt, resp.StatusCode);
if (attempt >= _maxRetries)
{
_logger.LogError("Giving up on logging after {MaxAttempts} attempts", _maxRetries);
break;
}
}
catch (HttpRequestException ex)
{
_logger.LogWarning(ex, "Transient error during logging attempt {Attempt}", attempt);
if (attempt >= _maxRetries)
{
_logger.LogError("Giving up on logging after {MaxAttempts} attempts", _maxRetries);
break;
}
}
// Exponential backoff
await Task.Delay((int)Math.Pow(2, attempt) * 100);
}
}
}
Registration and HttpClient Configuration
builder.Services.AddHttpClient("LoggingService", client =>
{
client.BaseAddress = new Uri("https://logs.example.com/");
client.Timeout = TimeSpan.FromSeconds(5);
});
app.UseMiddleware<ReliableLoggingMiddleware>();
This middleware respects the pipeline model, performs async downstream calls, captures timing including logging retries, and handles failure without blocking requests.
Edge Cases and Failure Modes in Middleware Pipelines
Middleware pipelines introduce complexity with potential failure modes—understanding them is crucial for resilient design.
| Scenario | Cause | Impact | Mitigation |
|---|---|---|---|
| Middleware does not call next | Missing await _next(context) | Request hangs, timeout, no further processing | Enforce code reviews & tests |
| Exception not handled | Middleware does not catch downstream exceptions | Server crash or 500 without custom formatting | Exception handling middleware first in pipeline |
| Improper response modification | Middleware modifies response headers/body improperly | Conflicting headers, invalid content | Validate headers before setting |
| Middleware ordering mistake | Authorization before Authentication | Permissions fail due to no identity | Follow recommended ordering |
| Middleware with state | Middleware keeps mutable shared state | Race conditions and data corruption | Use HttpContext.Items or scoped DI |
| Long blocking operations | Middleware performs blocking I/O | Thread pool starvation and request delays | Use async APIs and timeouts |
| Middleware throws during startup | Constructor throws or DI fails | App fails to start or requests fail early | Validate constructors and DI registration |
| Large response buffering | Middleware buffers entire response to memory | High memory consumption and backpressure | Stream responses or limit buffer size |
Request Timeout Scenario
When middleware calls downstream services or retries, requests might exceed client timeouts. Middleware should be aware of cancellation tokens:
public async Task InvokeAsync(HttpContext context)
{
CancellationToken token = context.RequestAborted;
await _next(context);
// downstream operations with cancellation support
}
Ignoring cancellation tokens leads to wasted resources and slow response termination.
Performance Considerations and Optimization
Middleware Overhead
Each middleware in the pipeline adds a small CPU and memory overhead due to delegate invocation, logging, and async state machines. In high-throughput environments:
- Keep middleware simple, avoid heavy computations.
- Minimize allocations and object capture in lambdas.
- Prefer endpoint filters or minimal APIs for light-weight concerns.
Avoiding Double Invocation of _next
Middleware must make exactly one call to _next(context) to avoid:
- Missing calls: request hangs or incomplete pipelines.
- Multiple calls: unexpected duplicated downstream execution, hard-to-debug bugs.
Patterns enforcing this include:
bool nextCalled = false;
try
{
await _next(context);
nextCalled = true;
}
catch { if(!nextCalled) /* handle */ }
Or adopting analyzer rules and code reviews.
Streaming Response Optimization
Middleware modifying responses should:
- Avoid buffering entire bodies unless necessary.
- Use
context.Response.Bodystream to process chunks. - Use
EnableBuffering()sparingly to allow upstream reads.
Streaming reduces memory footprint and improves latency.
Connection Limits and Thread Pool
Middleware making outbound HTTP calls (e.g., to logging services) must consider:
- HttpClient reuse and connection pooling.
- Thread pool starvation from blocking calls.
- Circuit-breakers or rate limiters to avoid cascading failures.
Add retries with backoff only for idempotent operations.
Observability Enhancement: Structured Logging and Distributed Tracing
Structured Logging Enrichment in Middleware
Use logging scopes to enrich logs with correlated contextual values consistently:
using (_logger.BeginScope(new Dictionary<string, object> { ["CorrelationId"] = correlationId }))
{
_logger.LogInformation("Processing {Method} {Path}", context.Request.Method, context.Request.Path);
await _next(context);
}
This allows centralized search/filtering of logs by CorrelationId in log aggregation systems (e.g. ELK, Seq).
Distributed Tracing Span Example with OpenTelemetry Middleware
Integrate OpenTelemetry tracing directly within custom middleware to create child spans:
public class TracingMiddleware
{
private readonly RequestDelegate _next;
private readonly Tracer _tracer;
public TracingMiddleware(RequestDelegate next, TracerProvider tracerProvider)
{
_next = next;
_tracer = tracerProvider.GetTracer("ExampleApp.Middleware.Tracing");
}
public async Task InvokeAsync(HttpContext context)
{
var spanName = $"{context.Request.Method} {context.Request.Path}";
using var span = _tracer.StartActiveSpan(spanName, SpanKind.Server);
span.SetAttribute("http.method", context.Request.Method);
span.SetAttribute("http.url", context.Request.Path);
try
{
await _next(context);
span.SetAttribute("http.status_code", context.Response.StatusCode);
}
catch (Exception ex)
{
span.SetStatus(Status.Error.WithDescription(ex.Message));
throw;
}
}
}
Register in pipeline before downstream:
app.UseMiddleware<TracingMiddleware>();
This pattern allows correlating distributed calls from inbound requests into downstream HTTP or database calls.
SLI/SLO and Alert Refinement
| SLI | Target (SLO) | Rationale | Alert Condition |
|---|---|---|---|
| Middleware-induced latency | p95 < 200ms | Maintain low middleware overhead | p95 latency > 500ms sustained 5 mins |
| Middleware error rate | <0.05% | Minimize failures affecting users | Error rate spikes > 0.2% in 5 mins |
| Correlation ID header presence | 100% | Required for traceability | Missing headers > 0.1% |
| Number of retries in logging | Average < 0.1 per req | Identify instability in logging infra | Logging retries > threshold |
| Overall request success rate | > 99.9% | Ensure pipeline reliability | HTTP 5xx > 0.5% sustained |
Alerts connected to middleware health must be tuned carefully to avoid noise while catching regressions quickly.
Middleware Pipeline Decision Checklist
Use this checklist when designing or extending middleware pipelines:
| Question | Considerations | Action |
|---|---|---|
| Does this logic fit at a global pipeline level? | Cross-cutting concerns like auth, logging require middleware | Use middleware |
| Is the concern tightly coupled to endpoint behavior or minimal? | Minimal request or response tweaks near handlers | Prefer endpoint filters (ASP.NET Core 7+) |
| Do I need scoped DI services? | Scoped services cannot be injected via simple middleware constructor | Use IMiddleware and register as scoped |
| Will adding this middleware impact latency noticeably? | Extra processing or network calls may add delay | Optimize and monitor with metrics |
| Does middleware promise to always call next()? | Missing calls cause requests to hang | Enforce strict coding and integration tests |
| Should error handling be centralized? | Error handling middleware must be earliest | Put error handler at pipeline root |
| Is meaningful logging including correlation possible? | Enrich logging with correlation ids | Use middleware to add and propagate IDs |
| How to handle request cancellations? | Support HttpContext.RequestAborted for resource cleanup | Pass cancellation token to async operations |
This checklist helps build secure, performant, and maintainable middleware pipelines.
Summary
- ASP.NET Core middleware composes as nested delegates forming an async call stack.
- Middleware lifetime is singleton-like unless implemented via
IMiddleware. - Careful error handling and guaranteed
_next()invocation govern pipeline health. - Complex production middleware often includes async operations with retry, correlation, and tracing.
- Edge cases like request cancellation, buffering, and ordering errors lead to failures.
- Performance tuning requires minimizing overhead, streaming responses, and managing thread pool.
- Observability richness depends on structured logs, OpenTelemetry span instrumentation, and precise metrics.
- A disciplined design checklist ensures middleware serves its purpose without impacting reliability.
Master these internal concepts and design decisions to create professional-grade ASP.NET Core middleware pipelines powering resilient large-scale services.