The decision is not as simple as "just add a header." The full implementation — with production-ready propagation across HttpClient calls, background jobs, message queues, and Serilog enrichment with OpenTelemetry integration — is available on Patreon, including the source code used at the enterprise level to trace requests across microservices reliably.

Understanding how correlation IDs fit into your broader observability strategy is exactly what Chapter 14 of the ASP.NET Core Web API: Zero to Production course covers — including structured logging, OpenTelemetry, and health checks, all wired together in a single production API codebase.

What Is a Correlation ID and Why Does It Matter?

A correlation ID is a unique identifier attached to an incoming request and propagated across every service, log entry, and background operation that request touches. When something goes wrong, you can filter your logs by a single ID and reconstruct the full request journey — across multiple APIs, message queues, and asynchronous jobs.

Without a correlation ID strategy, debugging distributed failures requires correlating timestamps, guessing which log entries are related, and hoping that nothing ran in parallel at the same time. With a solid strategy, you query one field and get the complete picture.

The challenge is that ASP.NET Core offers multiple mechanisms that seem to solve this problem — and teams frequently pick the wrong one for their context, or mix them in ways that create ambiguity rather than clarity.

The Three Approaches: An Overview

Custom Middleware with X-Correlation-ID Header

The most explicit approach: write middleware that reads an inbound X-Correlation-ID header (or generates a new GUID if none is present), stores it in HttpContext.Items, adds it to ILogger scope, and forwards it on all outbound HttpClient calls via a DelegatingHandler.

This gives you complete control over naming, storage, propagation strategy, and header format. It integrates cleanly with Serilog's LogContext.PushProperty so every log line within that request automatically carries the correlation ID.

The trade-off: it is entirely your responsibility. There is no standard, no automatic tooling support, and you must instrument every outbound call manually if you want propagation to work.

HttpContext.TraceIdentifier

HttpContext.TraceIdentifier is a built-in property that ASP.NET Core assigns to every request. It is a unique string identifier — in Kestrel it is formatted as {connectionId}:{requestCount}, which makes it deterministic but not human-friendly.

The appeal is obvious: it is always there, requires no middleware, and is already included in ASP.NET Core's default request logging (UseRouting, UseSerilogRequestLogging). You can read it anywhere you have access to IHttpContextAccessor.

The limitation: TraceIdentifier is an internal implementation detail. It is scoped to a single application instance. If you want to track a request across services, you cannot use TraceIdentifier as the propagation ID because it is never forwarded to downstream services by the framework. It is a local ID, not a distributed one.

W3C Trace Context (traceparent / tracestate)

W3C Trace Context is an IETF standard (RFC specification) that defines two headers: traceparent (carrying version, trace ID, parent span ID, and flags) and tracestate (vendor-specific metadata). ASP.NET Core fully supports this standard through System.Diagnostics.Activity and the ActivitySource API.

When OpenTelemetry is enabled, Activity.Current is automatically populated with W3C-compatible IDs. The TraceId on an Activity is a 128-bit identifier that propagates across service boundaries when downstream HttpClient calls are instrumented. Any OpenTelemetry-compatible backend — Jaeger, Zipkin, Grafana Tempo, Azure Monitor — understands this format natively.

The trade-off: the W3C approach is powerful and standards-compliant, but it adds complexity. You need OpenTelemetry instrumentation wired up, and the TraceId is verbose (a 32-character hex string) compared to a GUID. For simple scenarios — a single-service API or a small team — this can be more infrastructure than the problem warrants.

When to Use Which Approach

Use Custom Middleware (X-Correlation-ID) When:

• Your system is not using OpenTelemetry and you do not plan to introduce it soon

• You need a simple, human-readable ID in logs and error responses (e.g., to share with customers for support tickets)

• You want clients to be able to pass a correlation ID from the frontend (mobile apps, browser clients) and trace it end-to-end

• Your team is small and the infrastructure overhead of W3C trace context is not justified yet

• You need the ID to survive message queue boundaries (RabbitMQ messages, Azure Service Bus) where HTTP headers do not naturally propagate

This is the right starting point for most teams building their first distributed system. It is simple, explicit, and easy to reason about.

Use HttpContext.TraceIdentifier When:

• You need a quick, no-setup way to correlate logs within a single service

• You are not building a distributed system and the request never leaves one application

• You want something in logs immediately without writing middleware

• You are adding basic observability to a legacy application and cannot introduce new middleware yet

Never use TraceIdentifier as your correlation ID if the request touches more than one service. It will not propagate, and you will end up with per-service IDs that do not connect.

Use W3C Trace Context When:

• You are running OpenTelemetry (or plan to)

• Your observability tooling supports distributed tracing natively (Azure Application Insights, Grafana Tempo, Jaeger, Honeycomb)

• You have multiple services that all speak the same tracing language

• You care about span-level granularity, not just request-level correlation

• You are building a new system and can establish the right foundation from the start

W3C Trace Context is the right long-term choice for any team that is serious about distributed observability. It is the standard everything converges on.

Can You Use Both?

Yes — and in practice, most mature enterprise systems do. The pattern is:

• Use W3C Trace Context (Activity.Current.TraceId) as the primary distributed trace ID, handled by OpenTelemetry

• Use a custom X-Correlation-ID header as an application-level correlation ID that clients can pass and that survives non-HTTP boundaries (queues, cron jobs, emails)

• Enrich structured logs with both — the W3C trace ID for APM tooling correlation, and the application correlation ID for support ticket lookups

The key insight is that these two IDs serve different audiences: the trace ID serves your observability platform, and the application correlation ID serves your support team and your customers.

The W3C TraceId vs X-Correlation-ID Decision Matrix

Anti-Patterns to Avoid

Relying on TraceIdentifier for distributed tracing. This is the most common mistake. Teams log TraceIdentifier everywhere, then realise it changes per service and is completely useless for cross-service correlation.

Using a shared static correlation ID store. Some teams store the correlation ID in a static variable or a singleton instead of scoped to the request. In async code, this causes correlation IDs from concurrent requests to bleed into each other. Always scope correlation IDs to the request via HttpContext.Items or AsyncLocal<T>.

Not propagating on outbound calls. Generating a correlation ID on the inbound request but forgetting to add it to outbound HttpClient calls defeats the purpose entirely. Use a DelegatingHandler registered at the factory level so propagation is automatic and cannot be forgotten.

Mixing two different header names. Using X-Correlation-ID on some services and X-Request-ID on others means logs across services use different fields. Pick one header name and enforce it across the fleet as a standard.

Generating a new ID on every hop. The ID should only be generated if none arrives with the request. If the client or an upstream service sends a correlation ID, preserve and forward it — do not replace it. This is what allows end-to-end tracing from the client's first request.

What a Production Correlation ID Strategy Looks Like

A mature enterprise correlation ID strategy typically combines:

1. Inbound middleware — reads X-Correlation-ID (or generates a new GUID), stores it in HttpContext.Items, and sets it in ILogger scope

2. Outbound DelegatingHandler — reads the correlation ID from IHttpContextAccessor and adds it to every outbound request header automatically

3. Serilog enrichment — LogContext.PushProperty("CorrelationId", ...) so every log line in the request carries the field without manual effort

4. OpenTelemetry ActivitySource baggage — for services that use OTel, the correlation ID is added as activity baggage so it flows through the trace graph

5. Background job propagation — correlation IDs are embedded in message payloads (not just headers) so they survive queue round-trips and deferred execution

This level of depth — including edge cases like Hangfire jobs, Azure Service Bus handlers, and multi-tenant scenarios — is what separates a demo implementation from a production-ready one.

💻 Full source code for the correlation ID middleware — clone it, run it, and adapt it: github.com/codingdroplets/dotnet-request-correlation-middleware

Should You Use a NuGet Package?

There are established NuGet packages for correlation ID management in ASP.NET Core — stevejgordon/CorrelationId and skwasjer/Correlate being the most referenced. These are solid libraries and reasonable choices if you want the basics handled quickly.

The case against a package: correlation ID propagation is not complex to build, and owning the implementation means you understand exactly what is in scope. When you need to extend it — adding to Hangfire jobs, propagating through custom event buses, or integrating with a proprietary APM — a bespoke implementation is far easier to adapt. The package abstraction can become a constraint at the edges.

The case for a package: it handles the edge cases you have not thought of yet. For teams without a dedicated platform engineer, a well-maintained package is a pragmatic choice.

Neither answer is wrong. The trade-off is ownership vs convenience, and both are valid.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What is the difference between a correlation ID and a trace ID in ASP.NET Core?

A correlation ID is an application-level identifier — typically a GUID — that you generate and propagate explicitly, often via a custom X-Correlation-ID header. A trace ID (in the W3C sense) is a 128-bit identifier managed by the distributed tracing system (OpenTelemetry, Activity API). They serve overlapping but distinct purposes: the trace ID links spans for APM tooling; the correlation ID links log entries and is human-accessible for support workflows. Enterprise systems often carry both.

Should I use X-Correlation-ID or X-Request-ID as my header name?

Either works at the HTTP level, but standardise on one across your entire fleet. X-Correlation-ID is more widely used in .NET ecosystems and library documentation. X-Request-ID is common in Ruby/Rails and some gateway tools (NGINX, Envoy). If you control all services end-to-end, pick X-Correlation-ID and be consistent. If you integrate with third-party gateways or clients, check what they expect.

Does HttpContext.TraceIdentifier work for distributed tracing?

No. HttpContext.TraceIdentifier is scoped to a single application instance and is never forwarded to downstream services by ASP.NET Core. It is useful for correlating log entries within a single service, but cannot be used to trace a request across services. Use it only for single-service scenarios or as a supplementary field.

How do I propagate a correlation ID through Hangfire or Azure Service Bus in ASP.NET Core?

HTTP headers do not survive the queue boundary. The standard approach is to embed the correlation ID in the message payload or job parameter — as a top-level field, not in the message body. When the consumer processes the message, it reads the correlation ID from the payload and initialises it into the AsyncLocal<T> context or ILogger scope before executing any business logic.

Is W3C Trace Context the right choice for a single ASP.NET Core API with no downstream services?

Probably not. W3C Trace Context is designed for distributed systems. For a single-service API, the overhead of configuring OpenTelemetry exporters, managing Activity spans, and reasoning about trace IDs adds complexity without proportional benefit. For a single service, HttpContext.TraceIdentifier enriched into Serilog logs is sufficient. Add W3C Trace Context when you have a second service to connect to.

How do I add the correlation ID to every Serilog log entry automatically?

Use LogContext.PushProperty("CorrelationId", correlationId) inside your correlation ID middleware, within a using scope that covers the rest of the request pipeline. This enriches every ILogger.Log* call within that scope with the CorrelationId property, so you never have to pass it manually to individual log statements.

Can a client send their own correlation ID and have it propagated?

Yes, and this is often desirable in B2B APIs. Your middleware should check for an inbound X-Correlation-ID header and use that value if present (and validate it as a reasonable length/format), only generating a new ID if none is provided. This allows upstream services or API consumers to set the correlation ID at the point of origin and trace it all the way through your system.

If you want to see these patterns in practice with production-ready code and edge cases covered, the full implementations are available on Patreon — ready to run and adapt to your real codebase.

Understanding how this decision fits into your service registration strategy is equally important. The Keyed Services vs Factory Pattern vs Named Services in ASP.NET Core guide covers the DI side of this decision — worth reading alongside this article when the dispatch logic lives behind an interface.

What Problem Are We Actually Solving?

All three approaches address the same core challenge: selecting and executing the right behaviour at runtime based on a discriminant — a status, a payment method, an event type, a document format. The difference lies in how that selection is encoded, who controls it, and how easy it is to change later.

The naive starting point is an if-else chain or a switch statement. It works until it doesn't — typically when new cases appear, when the logic grows complex enough to demand unit testing at the individual branch level, or when two different parts of the codebase need to resolve the same discriminant independently.

Option 1: The Strategy Pattern with Dependency Injection

The Strategy Pattern encodes each branch as a separate class implementing a shared interface. ASP.NET Core's DI container registers all implementations, and a resolver — either a factory, a keyed service lookup, or an IEnumerable<T> filter — selects the right one at runtime.

The key advantage is that each strategy is independently testable, independently deployable in unit tests, and fully decoupled from the resolution logic. Adding a new case means adding a new class and registration, not touching existing code. This is the Open/Closed Principle in its most literal form.

The cost is ceremony. Three strategies mean three classes, three registrations, and a resolution mechanism that itself needs to be correct. For small, stable discriminant sets, this overhead is real.

When to reach for the Strategy Pattern:

• The number of variants is expected to grow (new payment providers, new notification channels, new document processors)
• Each variant has non-trivial logic that needs its own tests
• The strategy implementations have their own dependencies that should be injected
• The resolution happens across multiple call sites or services
• Extensibility via plugin or module registration is a future requirement

When to avoid it:

• The discriminant set is fixed and small (2-3 cases that will never expand)
• The logic per branch is a single line or trivially simple
• The extra classes add navigation burden without adding testability benefit

Option 2: Switch Expressions (C# 8+)

C# switch expressions, introduced in C# 8 and extended significantly through C# 13 and 14, bring pattern matching directly into the language. They support type patterns, property patterns, positional patterns, and relational patterns — making them far more powerful than a traditional switch statement.

A switch expression is the right tool when the dispatch logic is local, the result is a value (not a side effect), and the discriminant set is closed — meaning you control all the cases and new ones don't arrive at runtime.

The compiler provides exhaustiveness checking for enums and discriminated types, which means the switch expression fails at compile time if a case is missed — something neither dictionary dispatch nor the Strategy Pattern provides without extra effort.

When to reach for switch expressions:

• Mapping from one value to another (enum → string, status → HTTP code, tier → discount rate)
• The discriminant is a closed set under your control (an enum, a sealed type hierarchy)
• The branch logic is a simple expression, not a multi-step operation
• The dispatch is local to one method and not shared across services
• You want compile-time exhaustiveness guarantees

When to avoid them:

• Branches contain complex, multi-step logic that deserves its own test surface
• The discriminant set is open-ended or runtime-provided (plugins, user-configurable processors)
• The logic involves dependencies — injected services, async I/O, external calls

Option 3: Dictionary Dispatch

Dictionary dispatch maps a key to a Func<T>, Action, or pre-constructed handler object stored in a Dictionary<TKey, TValue>. It offers O(1) lookup by design and is the natural fit when the key space is large, when the mapping is built at runtime from dynamic configuration, or when the cost of switch compilation overhead (on very large switch blocks) matters.

In practice, dictionary dispatch is most useful when the mapping comes from data — from a configuration file, a database, or a set of registered plugins — rather than from compile-time case labels. It is also useful when multiple services each need to resolve their own subset of the same key space independently.

The downside is that dictionaries give up exhaustiveness checking entirely. Missing keys are runtime failures. The structure is harder to reason about when reading the codebase, because the reader must trace both the dictionary construction and the invocation site to understand the full dispatch graph.

When to reach for dictionary dispatch:

• The key-to-handler mapping is built from runtime data (configuration, database, plugin registration)
• The key space is large (dozens or more cases) and O(1) lookup is preferable to a long switch
• Multiple registration sources need to contribute to the same dispatch map
• The handlers are lightweight functions (delegates, lambdas) without DI dependencies

When to avoid it:

• The mapping is static and known at compile time (a switch expression is simpler and safer)
• The handlers have injected dependencies (use the Strategy Pattern instead)
• You need exhaustiveness guarantees (dictionary dispatch has none)

Side-by-Side Comparison

Real-World Trade-Offs

The Notification Routing Problem

Consider an ASP.NET Core API that dispatches notifications across email, SMS, push, and webhook channels. New channels will be added as the product grows. Each channel has configuration, retry logic, and templating concerns.

This is the Strategy Pattern problem. Each channel is a strategy, each strategy has dependencies, and the open-ended growth of the channel list is precisely the extensibility pressure the pattern is designed to absorb. Switch expressions and dictionary dispatch both require code changes for every new channel — which means the team that added the new channel has to understand the dispatch site, not just the new handler.

The HTTP Status Code Mapping Problem

Consider mapping a domain exception type to the appropriate HTTP status code in a global exception handler. The set of exception types is finite, controlled by the team, and the mapping is a pure value expression: NotFoundException → 404, ConflictException → 409, ValidationException → 422. This is a switch expression problem. Bringing in the Strategy Pattern for this adds four files of ceremony for what should be four lines of code.

The Payment Method Routing Problem with Runtime Plugins

Consider a payment processing platform where payment method handlers are registered as plugins from a database table. The handler for each payment method is resolved by a string key that comes from the database at startup. This is a dictionary dispatch problem — the mapping is built at runtime, the keys come from data, and the handlers are lightweight delegates that call into a pre-resolved service. The Strategy Pattern is still viable here but requires a more complex keyed-service setup; dictionary dispatch is simpler when the plugins are data-driven rather than code-driven.

What About Combining Them?

In practice, production codebases often combine all three. A common pattern in ASP.NET Core looks like this:

• Switch expression at the top of the pipeline to route between two or three broad categories
• Strategy Pattern within each category where the variants are open-ended and DI-managed
• Dictionary dispatch in specific hot paths where lookup performance matters and the keys come from runtime data

The mistake to avoid is defaulting to one approach regardless of context. Teams that over-apply the Strategy Pattern end up with an explosion of single-method classes. Teams that over-apply switch expressions end up with unmaintainable blocks that nobody wants to touch. Teams that over-apply dictionary dispatch end up with opaque mapping tables and silent runtime failures.

How This Connects to Common DI Mistakes

The Strategy Pattern's biggest failure mode in ASP.NET Core codebases is getting the service lifetime wrong — registering strategies as singletons when they depend on scoped services, or resolving them through a root provider and triggering the captured dependency problem. If your Strategy Pattern resolution involves any service lookup, the guidance in 7 Common ASP.NET Core Dependency Injection Mistakes (And How to Fix Them) directly applies — particularly the sections on captive dependencies and lifetime mismatches.

Making the Right Call for Your Team

Three questions guide the decision:

Is the variant set closed or open? If it is closed (you control all the cases and they are known at compile time), switch expressions give you compiler safety for free. If it is open, the Strategy Pattern earns its ceremony.

Does each variant have its own dependencies or complex logic? If yes, the Strategy Pattern is the right level of abstraction. If no, the overhead is not worth it.

Is the mapping data-driven or code-driven? If the key-to-handler mapping comes from runtime data, dictionary dispatch is the natural fit. If it comes from source code, switch expressions or the Strategy Pattern will be safer.

The best teams treat these as tools in a toolbox — not mutually exclusive philosophies. Applying the right tool to the right problem is what keeps .NET codebases readable and changeable over time.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What Is the Difference Between the Strategy Pattern and a Switch Expression in C#?

The Strategy Pattern encodes each behaviour variant as a separate class implementing a shared interface, with variant selection handled by a resolver or DI container at runtime. A switch expression is a language construct that selects a value or invokes logic inline based on a pattern match, with all cases defined at compile time. The Strategy Pattern is better for open-ended, dependency-carrying variants; switch expressions are better for closed value mappings where compile-time exhaustiveness checking is valuable.

When Should I Prefer a Switch Expression over the Strategy Pattern in ASP.NET Core?

Use a switch expression when the dispatch is mapping from one value to another (for example, status to HTTP code or enum to string), when the set of cases is fixed and compiler-controlled, and when the branch logic is a simple expression rather than a multi-step operation with dependencies. The Strategy Pattern adds a level of indirection that is only justified when the variants are independently testable, have injected dependencies, or are expected to grow over time.

Is Dictionary Dispatch Faster Than a Switch Expression in .NET?

For small to medium discriminant sets (up to roughly 6-7 cases), the C# compiler generates optimised jump tables or binary search trees for switch expressions that are typically faster than dictionary hash lookups. For larger sets (dozens or hundreds of keys), dictionary dispatch at O(1) can outperform the switch. In practice, the performance difference is rarely the deciding factor — correctness, testability, and maintainability should drive the choice first.

Can I Combine the Strategy Pattern with Dictionary Dispatch in ASP.NET Core?

Yes, and it is a common production pattern. The Strategy Pattern defines the interface and implementations; dictionary dispatch (or keyed services) provides the resolution mechanism that maps from a runtime key to the correct strategy instance. This combination gives you the extensibility and testability of the Strategy Pattern with the O(1) runtime lookup of dictionary dispatch. ASP.NET Core's keyed DI services (AddKeyedSingleton, AddKeyedScoped) are the idiomatic way to achieve this since .NET 8.

What Are the Risks of Using Dictionary Dispatch for Behaviour Routing in .NET?

The primary risk is silent runtime failure: if a key is missing from the dictionary, the code throws a KeyNotFoundException at runtime rather than failing at compile time. Unlike a switch expression with an exhaustive pattern match or an enum, the compiler cannot verify that all expected keys are handled. Dictionary dispatch also makes the routing logic harder to trace during a code review or debugging session, because the reader must follow both the dictionary construction and the call site to understand the full dispatch graph. Always include a fallback or explicit null-check for missing keys.

How Does the Strategy Pattern Interact with Scoped Service Lifetimes in ASP.NET Core?

Strategy implementations should be registered with the same lifetime as their most restrictive dependency. If a strategy depends on a scoped service (such as a DbContext), the strategy itself must be scoped — not singleton. Resolving scoped strategies through a DI-registered factory is straightforward; the risk appears when teams store strategy instances in a singleton resolver without accounting for lifetime. This is covered in detail in the dependency injection mistake guides, and it is one of the most common production issues with Strategy Pattern implementations in ASP.NET Core services.

Should I Use the Strategy Pattern for Simple Two-Case Dispatch in .NET?

Generally, no. For two fixed cases — or even three — the ceremony of the Strategy Pattern (interface, two implementation classes, registration, resolver) is not justified unless the variants are expected to grow or each variant has non-trivial logic requiring independent testing. A switch expression or a simple conditional is more readable and easier to maintain for a small, stable discriminant set. Reserve the Strategy Pattern for situations where extensibility and independent testability are genuine requirements, not theoretical ones.

The full implementations — including lifecycle validation, IServiceScopeFactory patterns, and edge-case handling — are available as annotated, production-ready source code on Patreon, ready to drop into real ASP.NET Core projects.

Understanding these mistakes also matters beyond the immediate fix. DI lifetime decisions are architectural decisions. Getting them right in Chapter 1 of the Zero to Production course is one of the first things covered — because everything that follows depends on services being registered with the right lifetime.

This article covers seven DI mistakes that appear repeatedly in ASP.NET Core codebases — from startups to enterprise teams — and explains the fix for each one.

Mistake 1: Injecting a Scoped Service Into a Singleton (The Captive Dependency)

This is the most well-known DI mistake in ASP.NET Core, and it still ships to production regularly. The term "captive dependency," coined by Mark Seemann, describes exactly what happens: a singleton holds a shorter-lived service captive, preventing it from being disposed and reusing stale state across requests.

A typical scenario: a singleton background processor injects AppDbContext directly via constructor injection. AppDbContext is registered as scoped — one per request — but the singleton is created once and never recreated. The captured DbContext instance is now shared across all concurrent operations for the lifetime of the application.

What actually goes wrong:

• EF Core's DbContext is not thread-safe. Sharing it across concurrent requests causes InvalidOperationException: A second operation was started on this context before a previous operation completed.

• Scoped services that cache per-request data (like a current user resolver or a tenant identifier) will return the data from the first request that initialized the singleton. Every subsequent request gets the wrong context.

• ASP.NET Core's scope validation (enabled by default in the Development environment) will throw an InvalidOperationException at startup if it detects this misconfiguration. Production builds often have scope validation disabled, which is why this can silently reach production.

The fix: When a singleton genuinely needs to access a scoped service, inject IServiceScopeFactory and create an explicit scope for each unit of work. This is the documented pattern for BackgroundService and hosted services that need database access. Creating a scope manually gives you control over the lifetime, and the scope — along with everything it resolves — is disposed correctly when the using block exits.

Alternatively, reconsider whether the service truly needs to be a singleton. Many services registered as singletons for performance reasons are perfectly safe as scoped — and the performance difference is negligible compared to a single database round-trip.

Mistake 2: Using the Service Locator Pattern

The service locator pattern means calling IServiceProvider.GetService<T>() (or GetRequiredService<T>()) from inside a class to resolve dependencies on demand, rather than declaring them as constructor parameters. It is technically supported, but it is an anti-pattern in ASP.NET Core DI.

The problem is not correctness — it works. The problem is that it hides dependencies. When a class takes IOrderRepository, IEmailSender, and IEventPublisher in its constructor, those dependencies are explicit. Every caller knows what this class needs. When a class takes IServiceProvider and resolves whatever it needs internally, none of that is visible.

Concrete consequences:

• Unit testing becomes painful. Mocking three concrete dependencies is straightforward. Mocking an IServiceProvider that returns the right thing for any type passed to it is not.

• Misconfigured registrations fail at runtime, not at construction time. Constructor injection fails fast at startup. Service locator fails at the call site, which may be deep in a request lifecycle.

• Code that looks simple acquires hidden coupling to the entire DI container. Refactoring becomes harder as the true dependency graph is obscured.

The fix: Declare every dependency as a constructor parameter. If a class is growing to 6-8 constructor parameters, that is a signal that the class is doing too much — not a reason to switch to service locator. Split the class first, then inject cleanly.

The only legitimate use case for service locator in ASP.NET Core is infrastructure code that genuinely cannot use constructor injection: middleware classes (where scoped services must be resolved in Invoke/InvokeAsync), factories that create objects based on runtime conditions, and bootstrapping code in Program.cs. Outside of those cases, constructor injection is always the right choice.

Mistake 3: Registering Services With the Wrong Lifetime

Choosing the wrong service lifetime is a common source of subtle bugs. The three lifetimes have clear meanings:

• Transient — a new instance every time the service is resolved

• Scoped — one instance per HTTP request (or per manually created scope)

• Singleton — one instance for the entire application lifetime

The mistake is not always injecting scoped into singleton (Mistake 1). There are two other common misregistrations:

Transient services that hold state. A service registered as transient that holds internal mutable state (a counter, a cache, a buffer) will appear to work correctly in single-threaded tests but will produce incorrect results in production. Each resolution gets a fresh instance — the state is never shared, never accumulated. If you need state that persists across calls within a request, the service should be scoped.

Singletons that use HttpContext. A singleton that takes IHttpContextAccessor will compile and run, but IHttpContextAccessor.HttpContext is only valid during an active request on the current thread. A singleton that caches HttpContext properties at construction time, or accesses them from a background thread, will read null or stale data. Services that are inherently per-request must be registered as scoped, full stop.

What is genuinely safe as singleton: Pure utility services with no mutable state, configuration wrappers, registered IOptions<T> snapshots, clients like HttpClient (managed through IHttpClientFactory), and external SDK clients explicitly designed for thread-safe singleton use.

The fix: Before registering any service, answer three questions: Does it hold mutable state that should be reset per request? Does it access HttpContext or any request-scoped data? Does it wrap a resource (like a DbContext) that is explicitly not thread-safe? If yes to any of these, the service should be scoped — not singleton, not transient.

Mistake 4: Ignoring Disposable Transient Services

When a transient service implements IDisposable or IAsyncDisposable, the ASP.NET Core DI container takes ownership of its disposal — but only when it is resolved from a scoped context. The container holds a reference to every disposable transient it creates so it can call Dispose() when the scope ends.

This is the intended behaviour. The problem arises when transient disposables are resolved from the root container — directly from IServiceProvider during application startup, or in singleton services that create their own resolution context. In those cases, the root container holds the disposable for the entire application lifetime. There is no scope end to trigger disposal. The result is a memory leak that grows for as long as the application runs.

Why it is hard to catch: In development, applications restart frequently. The leak is invisible. In production, behind a load balancer with infrequent restarts, memory grows steadily. By the time it is investigated, the connection between the leak and the DI configuration is not obvious.

The fix: Avoid IDisposable on transient services unless the service genuinely manages a resource that must be released immediately. If disposal is needed, prefer scoped registration — the scope provides a natural disposal boundary. When resolving transient disposables manually (in tests or factory code), use explicit using blocks with manually created scopes to ensure deterministic disposal.

Mistake 5: Over-Registering Services as Singletons for Performance

Singleton registration is sometimes chosen for performance reasons: "Why create a new instance on every request if the class is stateless?" This reasoning is often correct, but it leads to a habit of defaulting to singleton for anything that looks lightweight — and that habit eventually produces the captive dependency problem at scale.

There is also a subtler issue: classes that appear stateless sometimes are not. Thread-local state, internal lazy-initialized caches, or dependencies that hold state (registered transitively through constructor injection) can all make a "stateless" class stateful in ways that are not obvious from the registration call.

The fix: Default to scoped for services that interact with any request-specific data, infrastructure, or external systems. Use singleton deliberately and explicitly only when you have confirmed the service is genuinely stateless and thread-safe. The performance cost of scoped over singleton is negligible for anything that does real work — it is measured in nanoseconds of allocation, while your slowest database query is measured in milliseconds.

When in doubt, profile first. Do not optimise DI lifetime without a measurement that shows lifetime choice is the bottleneck.

Mistake 6: Registering Multiple Implementations and Resolving the Wrong One

ASP.NET Core allows multiple implementations of the same interface to be registered. When you call services.AddScoped<INotificationService, EmailNotificationService>() and later call services.AddScoped<INotificationService, SmsNotificationService>(), both registrations are valid. Resolving INotificationService from the container returns the last registration — SmsNotificationService. The email implementation is effectively hidden.

This surprises developers because it is different from how most other DI containers behave, and it is different from what you might expect if you have worked with configuration overriding.

Where this bites teams:

• Integration tests that register a mock implementation after the real one (expecting to override) find that the mock is resolved correctly — but only if test setup registers last. If the production registration somehow runs after the test setup, the real implementation wins.

• Modules or plugins that add implementations to an existing interface without knowing about prior registrations can silently replace behaviour.

• Resolving IEnumerable<INotificationService> correctly returns all implementations in registration order. Teams that expect INotificationService (singular) to give them all implementations are surprised when only the last one is returned.

The fix: When you intend to have multiple implementations, design for it explicitly. Use IEnumerable<T> injection when a consumer needs all implementations. Use named/keyed services (available natively in .NET 8+ via AddKeyedScoped) when different consumers need different implementations. Never rely on implicit registration order to control which implementation is resolved — make the selection explicit.

Mistake 7: Constructing Dependencies Outside the DI Container

This is the mistake that looks harmless in isolation: var service = new MyService(new MyRepository(new AppDbContext(options))). It compiles. It runs. It works in unit tests. But it breaks the DI system in ways that accumulate.

What goes wrong:

• The constructed object and its entire dependency tree are invisible to the DI container. No lifetime management. No scope boundary. No disposal by the framework.

• If MyService is later refactored to depend on a new service, every call site where it is manually constructed must be updated. Constructor injection centralises this — new scatters it.

• Factories, decorators, and pipeline behaviours registered in the DI container do not apply to manually constructed objects. An object created with new bypasses middleware, logging behaviour, and any cross-cutting concern wired through the container.

In production ASP.NET Core code, manually constructing services is rarely justified. The cases where it is legitimate: creating simple, truly static value objects (records, configuration structs) that have no runtime dependencies, and constructing test doubles in unit test arrangement code where DI adds no value.

The fix: Register everything in the DI container. If a service needs to be created dynamically at runtime (based on a type identifier, a feature flag, or runtime data), use a factory — but register the factory itself in the container and let it resolve its dependencies through the container.

How to Audit Your Codebase for DI Mistakes

Running ValidateScopes = true and ValidateOnBuild = true in development (which is the default behaviour in ASP.NET Core's Development environment) will catch captive dependencies at application startup. This is the first and most valuable automated check.

Beyond that, a targeted code review for:

• Any class that takes IServiceProvider as a constructor parameter (service locator)

• Any IDisposable service registered as transient

• Any singleton that holds a reference to HttpContext or IHttpContextAccessor

• Any new ServiceType(...) outside of test setup code

This is not a comprehensive list, but it covers the most common sources of DI-related production failures.

DI in ASP.NET Core is powerful precisely because it handles object lifetime, disposal, and dependency resolution automatically — but only for objects registered in the container. Every workaround to that system trades short-term convenience for long-term instability.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

Frequently Asked Questions

What is a captive dependency in ASP.NET Core DI? A captive dependency occurs when a longer-lived service (typically a singleton) holds a reference to a shorter-lived service (scoped or transient). The shorter-lived service is never released because the singleton's lifetime controls when it is disposed. This leads to stale data, thread-safety violations, and memory leaks. The standard fix is to inject IServiceScopeFactory into the singleton and create an explicit scope when the scoped service is needed.

Why should I avoid the service locator pattern in ASP.NET Core? The service locator pattern uses IServiceProvider.GetService<T>() to resolve dependencies at call time rather than declaring them as constructor parameters. While it works, it hides dependencies, makes unit testing significantly harder (you must mock the entire service provider), and causes misconfiguration errors to surface at runtime rather than at startup. Constructor injection is always preferred except in infrastructure code like middleware or application bootstrapping.

Can I register multiple implementations of the same interface in ASP.NET Core DI? Yes. Registering multiple implementations of the same interface is supported. However, resolving the interface by type (e.g., INotificationService) returns only the last registered implementation. To access all implementations, inject IEnumerable<INotificationService>. To direct different consumers to different implementations, use keyed services (introduced natively in .NET 8 via AddKeyedScoped, AddKeyedSingleton, etc.).

What happens if a transient service implements IDisposable in ASP.NET Core? The DI container tracks disposable transient services and calls Dispose() on them when the enclosing scope ends. This is correct behaviour within a request scope. The problem arises when disposable transients are resolved from the root container (outside any request scope) — the root container holds them for the application's entire lifetime, causing a memory leak. Disposable transients should always be resolved within a properly scoped context.

How do I validate my DI registrations at startup in ASP.NET Core? ASP.NET Core validates scope violations and resolves all services on build in the Development environment by default. You can explicitly enable this in any environment by setting ValidateScopes = true and ValidateOnBuild = true on the host builder's UseDefaultServiceProvider call. This catches captive dependencies (scoped services injected into singletons) at startup rather than at runtime during a request.

What is the difference between Scoped and Transient service lifetimes? Scoped services are created once per HTTP request (or per manually created IServiceScope) and shared across all resolutions within that scope. Transient services are created fresh every time they are resolved — even multiple times within the same request. Scoped is appropriate for services that hold per-request state (like a DbContext or a current user service). Transient is appropriate for lightweight, stateless services where a new instance per use is safe and desirable.

Should I default new services to Scoped, Transient, or Singleton? For most application services in ASP.NET Core APIs, scoped is the safest default. It gives each request its own instance (avoiding thread-safety concerns) while limiting allocation to once per request (avoiding the overhead of transient). Use singleton only for provably thread-safe, stateless services. Use transient for very lightweight utility objects where per-resolution creation is genuinely needed. When in doubt, start with scoped and optimise with measurement.

Chapter 14 of the ASP.NET Core Web API: Zero to Production course covers structured logging with Serilog, OpenTelemetry traces and metrics, and health check endpoints with liveness and readiness semantics — exactly the topics that come up in senior .NET interviews. It walks through a full production codebase so the context is always clear.

The questions are grouped by difficulty — Basic, Intermediate, and Advanced — so you can start with fundamentals and work toward the senior-level topics that separate candidates in 2026.

Basic Questions

What is the difference between ILogger<T> and ILoggerFactory in ASP.NET Core?

ILogger<T> is a strongly-typed logger scoped to a specific class. The generic type argument T becomes the category name, which is typically the fully qualified class name. This makes it easy to filter logs by class in production.

ILoggerFactory is a lower-level abstraction used to create loggers with arbitrary category names. It is useful in cases where the category name cannot be determined at compile time — for example, inside a helper class that creates child loggers dynamically.

In practice, inject ILogger<T> in your application classes. Use ILoggerFactory only when you genuinely need to create loggers with dynamic category names, such as inside framework-level infrastructure code.

What are log levels in ASP.NET Core, and when should you use each?

ASP.NET Core defines six log levels in ascending severity:

• Trace — the most detailed, typically disabled in production; used for step-by-step flow tracing during development.

• Debug — development-time diagnostics; disabled by default in production.

• Information — significant application events such as startup, request completion, and business-level milestones.

• Warning — unexpected but recoverable situations; for example, a configuration value falling back to a default.

• Error — a failure that affects the current operation but not the overall application; for example, an unhandled exception for a single request.

• Critical — a failure that requires immediate attention and may prevent the application from continuing; for example, a database connection failure at startup.

At a senior level, the key distinction interviewers expect is: use Warning for recoverable anomalies that indicate a potential problem worth investigating, and use Error only for failures that impact a specific operation without crashing the process. Over-using Error creates alert fatigue in production monitoring systems.

What is structured logging, and why does it matter?

Structured logging means recording log entries as structured data — typically key-value pairs — rather than plain text strings. Instead of writing "User 42 placed order 99", you write a log event with discrete properties: userId = 42, orderId = 99, eventType = "OrderPlaced".

This matters in production because structured logs can be queried, aggregated, and filtered by tools like Seq, Grafana Loki, or Azure Application Insights without parsing text. You can ask: "Show me all requests where orderId = 99 completed with a 500 status" and get exact results.

In ASP.NET Core, structured logging is supported through the ILogger message template syntax using named placeholders: _logger.LogInformation("Order {OrderId} placed by user {UserId}", orderId, userId). The curly-brace syntax binds values to named properties rather than positional string substitution.

How do you configure Serilog in ASP.NET Core?

Serilog replaces the built-in logging pipeline via UseSerilog() on the host builder. You configure it by defining sinks (outputs) such as Console, File, or Seq, and setting minimum log levels per namespace.

A minimal production-ready setup typically uses at least a Console sink for container environments and a rolling-file sink for local debugging. Enrichers like FromLogContext() and WithMachineName() add contextual properties automatically to every log event.

The recommended pattern is to configure Serilog early in Program.cs — before the host is built — so that startup errors are captured rather than silently lost.

For a detailed comparison of Serilog, NLog, and the built-in ILogger across enterprise scenarios, see ASP.NET Core Structured Logging: Serilog vs NLog vs ILogger.

What is UseSerilogRequestLogging() and when should you use it?

UseSerilogRequestLogging() is middleware from the Serilog.AspNetCore package that replaces ASP.NET Core's default per-request log output with a single, richer structured event per request.

The default ASP.NET Core logging emits two or more log lines per request across different categories. Serilog's middleware collapses these into a single event that includes the HTTP method, path, status code, elapsed milliseconds, and any properties added to the log context during the request.

Use it in every production ASP.NET Core application. It reduces log volume, improves query performance in log aggregation tools, and makes request-level diagnostics significantly easier.

Intermediate Questions

What is the difference between Log.Warning and _logger.LogWarning, and which should you use?

Log.Warning is the static Serilog.Log API — a static facade that writes to the globally-configured Serilog logger. _logger.LogWarning uses the ILogger<T> interface injected via ASP.NET Core's DI system.

Always prefer _logger.LogWarning (the ILogger<T> interface) in application code. It is testable — you can mock ILogger<T> in unit tests and verify log calls. It is also DI-friendly, keeping your code decoupled from the specific logging library.

The static Log facade is acceptable for bootstrapping code (e.g., early Program.cs startup before DI is available), but it should not be used inside services, controllers, or handlers.

What are log scopes in ASP.NET Core, and how do you use them?

Log scopes allow you to attach contextual properties to all log events emitted within a defined code block. They are created using ILogger.BeginScope().

A common use case is attaching a correlation ID or tenant ID to every log event produced while processing a specific request or job, without having to pass the value explicitly to every log call. When the scope is disposed (typically at the end of a using block), the properties are automatically removed.

In Serilog, scopes map to enrichment via LogContext.PushProperty(). ASP.NET Core's ILogger interface bridges the two transparently when Serilog is configured as the provider.

Senior candidates are expected to distinguish between log scopes (contextual enrichment within a code block) and log categories (the class-level name on ILogger<T>) — they serve different purposes and are often confused.

What is the three-pillar model of observability, and how does ASP.NET Core support it?

Observability in distributed systems is built on three signals:

• Traces — distributed, causally-linked records of work across services; essential for understanding latency and failures in request flows that span multiple components.

• Metrics — numerical measurements over time (counters, gauges, histograms); used for dashboards, SLOs, and alerting.

• Logs — discrete, time-stamped records of events with context; used for debugging and audit.

ASP.NET Core supports all three natively. Structured logging via ILogger covers logs. The System.Diagnostics namespace with Activity and ActivitySource covers traces. System.Diagnostics.Metrics covers metrics.

OpenTelemetry provides the vendor-neutral export layer that connects these signals to backend platforms like Jaeger, Prometheus, Azure Monitor, or Grafana LGTM.

Senior candidates are expected to articulate how all three work together — not treat them as separate tools.

How does OpenTelemetry work in ASP.NET Core, and why is it preferred over direct SDK integrations?

OpenTelemetry is a vendor-neutral observability framework that provides a single API and SDK for capturing traces, metrics, and logs. In ASP.NET Core, it integrates via the OpenTelemetry.Extensions.Hosting package.

You configure it by adding trace providers (e.g., AddAspNetCoreInstrumentation(), AddHttpClientInstrumentation()), metric providers, and exporters in Program.cs. The exporters send data to your observability backend — OTLP for Jaeger/Tempo/Grafana, Prometheus for metrics, or Azure Monitor for Microsoft-stack shops.

The advantage over direct SDK integrations (such as the Application Insights SDK or Datadog's .NET agent) is portability. With OpenTelemetry, you can switch your observability backend without changing application code. You write instrumentation once; exporters handle the transport.

For a full walkthrough, see OpenTelemetry in ASP.NET Core: A Complete Guide for .NET Developers.

What is the difference between liveness, readiness, and startup probes in ASP.NET Core health checks?

These three probe types come from Kubernetes terminology, and ASP.NET Core health checks map directly to them:

• Liveness — answers "Is this process alive and functional?" If a liveness check fails, Kubernetes restarts the pod. A liveness check should be minimal — typically just verifying that the application is not deadlocked or in an unrecoverable error state. Connecting to a database in a liveness check is an anti-pattern; a flaky DB connection should not restart your pod.

• Readiness — answers "Is this instance ready to receive traffic?" A readiness check failure removes the pod from the load balancer rotation without restarting it. Include dependency checks here (database reachability, downstream service availability) if those dependencies are required to serve requests.

• Startup — answers "Has the application finished initialising?" Relevant for apps with long startup sequences. Kubernetes waits for the startup probe to pass before enabling liveness and readiness probes.

In ASP.NET Core, you register health checks via AddHealthChecks() and tag each check with HealthCheckTags.Live or HealthCheckTags.Ready. Map them to separate endpoints: /health/live for liveness and /health/ready for readiness.

For a deeper comparison of probe semantics, see ASP.NET Core Health Checks: Liveness vs Readiness vs Startup Probes.

You can also explore production-ready health check implementations in the GitHub repo — with custom IHealthCheck implementations, tagged checks, and Kubernetes-ready endpoints.

What is AddDbContextCheck() and when should you use it?

AddDbContextCheck<TContext>() is a built-in health check extension from Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore that verifies a DbContext can connect to its database. It executes a CanConnectAsync() call against the database under the hood.

Use it in your readiness check, not your liveness check. A database connectivity failure means your application cannot serve requests (readiness concern), but it does not mean the application process itself is unhealthy (liveness concern).

Important caveat: AddDbContextCheck() only verifies connectivity, not schema consistency or query performance. For production scenarios, consider supplementing it with a lightweight query against a known table.

Advanced Questions

How do you implement correlation IDs in a distributed ASP.NET Core system, and how do they connect to distributed traces?

Correlation IDs are unique identifiers attached to a request that flow through all log events and downstream calls produced during that request's lifetime. They enable you to reconstruct the complete execution path for a single user request across multiple services and log aggregation queries.

In ASP.NET Core, the common pattern is middleware that inspects an X-Correlation-ID header on incoming requests. If the header is present, it uses the provided value; if not, it generates a new Guid. The ID is then added to the current ILogger scope via LogContext.PushProperty() (Serilog) or BeginScope() (ILogger), so every log event in that request automatically includes the correlation ID.

For distributed traces, the W3C traceparent header propagation built into System.Diagnostics.Activity and OpenTelemetry is the modern replacement. Activity.TraceId and Activity.SpanId are the trace-native equivalents of manual correlation IDs. The key insight for senior candidates: when using OpenTelemetry, you should correlate log events to trace spans using Activity.Current.TraceId rather than managing a separate correlation ID.

What is LoggerMessage source generation, and when should you use it?

LoggerMessage is a code-generation approach to structured logging that pre-compiles log messages into strongly-typed static delegates, eliminating the allocations and string parsing overhead of the standard ILogger.Log methods.

There are two approaches: the classic LoggerMessage.Define() factory methods (pre-.NET 6) and the newer source-generated approach using [LoggerMessage] attribute on partial methods (available from .NET 6 onwards). The source-generated version is cleaner and recommended for all new code.

Use LoggerMessage-generated methods in hot paths — high-throughput endpoints, inner loops, or request handlers where the logging overhead is measurable. In practice, this means anywhere you might log hundreds of thousands of events per second.

For typical line-of-business APIs, the overhead of regular ILogger.LogInformation() calls is negligible. The cost-benefit of LoggerMessage is only meaningful at high throughput. Senior candidates should know when to use it — not reflexively apply it everywhere.

How do you handle PII (Personally Identifiable Information) in ASP.NET Core logs?

PII in logs is a compliance and security risk. Strategies for managing it fall into three categories:

1. Destructuring policies (Serilog): Serilog's IDestructuringPolicy lets you intercept and redact or mask properties on objects before they are serialised into log events. You can register policies that replace email addresses, phone numbers, or credit card fields with masked equivalents.

2. Log templates discipline: The simplest approach is never logging raw user-supplied data. Pass only identifiers (e.g., userId, orderId) into log messages, never full names, emails, or addresses. This requires consistent code review discipline rather than automated enforcement.

3. Minimum log levels and filter configuration: Set minimum log levels for namespaces that may produce PII-heavy output (e.g., Microsoft.AspNetCore.HttpLogging logs request/response bodies by default). Disable body logging in production unless you have an explicit, compliant reason to enable it.

The key point for senior interviews: PII handling in logs is not just a technical problem — it is a governance problem. The technical controls enforce what the team decides as policy. Engineers need to understand both layers.

What is the difference between metrics, traces, and logs, and when would you use each for production debugging?

These three signals serve different diagnostic purposes and are most effective when used together:

Logs are the first tool for understanding what happened during a specific request or operation. They provide exact event records with context. Use logs when you know the time window and can search by entity identifiers.

Metrics tell you the shape of a problem across the fleet. High error rate, elevated p99 latency, or a drop in requests per second are all visible in metrics before any individual log is examined. Use metrics for detection — they tell you something is wrong before you know what.

Traces bridge the gap between "something is slow" (metrics) and "here is exactly where the time went" (logs). A distributed trace shows the causal chain of spans across services, making latency attribution in multi-service architectures possible. Use traces when you need to understand where time is spent or where failures propagate across service boundaries.

The senior-level answer is not to choose one — it is to use all three in the correct sequence: metrics surface the problem, traces isolate the location, logs explain the details.

How do you avoid common structured logging mistakes in production ASP.NET Core APIs?

The most costly structured logging mistakes in production:

1. Synchronous sinks on hot paths. File and database sinks should always be configured as asynchronous. Synchronous writes from within request-handling code add measurable latency under load. Serilog's WriteTo.Async() wrapper buffers writes off the request thread.

2. Over-logging at high severity. Excessive use of LogError for expected, recoverable conditions (e.g., 404 Not Found) causes alert noise. LogWarning for 4xx client errors and LogError only for 5xx server-side failures is the correct split.

3. String interpolation instead of structured templates. _logger.LogInformation($"User {userId} logged in") loses the structured property. _logger.LogInformation("User {UserId} logged in", userId) preserves it. This is a common mistake that turns structured logging back into plain text.

4. Capturing exception messages on 500s. exception.Message should never appear in 500-level responses. Log the full exception object (via LogError(ex, ...)) for internal diagnostics, but never expose it to API consumers.

5. No minimum log level configuration per namespace. Logging Microsoft.EntityFrameworkCore at Verbose in production generates enormous SQL query logs. Always configure per-namespace minimum levels in appsettings.json.

For a more detailed treatment of these patterns, see 7 Common ASP.NET Core Logging Mistakes (And How to Fix Them).

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

Frequently Asked Questions

What observability topics are most commonly asked about in senior .NET interviews? The most frequent topics are structured logging (Serilog configuration, named placeholders, enrichers), OpenTelemetry integration (auto-instrumentation, trace correlation, exporters), health check semantics (liveness vs readiness), and production anti-patterns like logging PII or using synchronous sinks. Interviewers in 2026 also increasingly ask about LoggerMessage source generation for performance-conscious candidates.

Is knowing Serilog required for .NET senior interviews, or is the built-in ILogger enough? You are expected to understand ILogger<T> deeply — it is the abstraction used in all production code. Serilog knowledge is a strong differentiator. Most production .NET teams use Serilog or NLog as the logging provider behind ILogger, and interviewers at companies running real production systems will often ask about Serilog specifically. Understanding both the abstraction and a concrete provider is the safe baseline.

What is the difference between OpenTelemetry and Application Insights SDK? Application Insights SDK is a Microsoft-specific, proprietary telemetry solution that sends data directly to Azure Monitor. OpenTelemetry is a vendor-neutral standard that can export to any compatible backend, including Azure Monitor (via the Azure Monitor Exporter), Jaeger, Grafana, or Datadog. OpenTelemetry is the modern, portable choice; the Application Insights SDK ties you to Azure. In interviews, the correct answer is to prefer OpenTelemetry for new projects and use the Azure Monitor Exporter if you need Azure Monitor.

How do I explain health checks to a non-technical interviewer or system design discussion? Frame it as: "Health checks expose endpoints that tell infrastructure orchestrators — like Kubernetes — whether this instance is ready to serve requests and whether it is functioning correctly." Liveness tells Kubernetes whether to restart the pod. Readiness tells the load balancer whether to route traffic to it. The analogy is a car's dashboard warning lights: one tells you to pull over immediately (liveness), another tells you the engine isn't warm enough yet (readiness).

What is Activity.TraceId, and how does it relate to distributed tracing in ASP.NET Core?Activity.TraceId is a 16-byte identifier from System.Diagnostics.Activity that uniquely identifies a distributed trace across all services involved in a single request. In ASP.NET Core with OpenTelemetry, the W3C traceparent header propagates this ID between services automatically. Every span in the trace shares the same TraceId, enabling tools like Jaeger or Grafana Tempo to stitch all related spans into a single trace view. Activity.SpanId identifies the individual unit of work within that trace.

Should I log request and response bodies in production for debugging purposes? Generally, no. Request and response body logging should be disabled in production unless there is a specific, compliance-reviewed need. Body logging at scale adds significant I/O overhead, risks capturing PII or sensitive tokens, and generates enormous log volume. For targeted debugging, prefer structured event logs with entity identifiers and status codes. If body logging is genuinely needed for compliance audit purposes, ensure it is scoped to specific endpoints, PII is masked, and retention is governed by your data policies.

What's the cleanest way to add a correlation ID to every log event in ASP.NET Core? Register middleware early in the pipeline that extracts or generates the correlation ID, stores it in HttpContext.Items, and pushes it to the ILogger scope with LogContext.PushProperty() (Serilog) or BeginScope() (ILogger). All downstream middleware, controllers, and services then emit log events that automatically include the correlation ID without any additional plumbing. This is preferable to passing the ID as a parameter through every method call.

Three approaches dominate audit logging strategy in ASP.NET Core APIs: request-level middleware that captures HTTP traffic, EF Core SaveChanges interceptors that capture data mutations at the persistence layer, and domain event handlers that capture business-meaningful state changes from within the domain model. Each has a rightful place — and each is the wrong choice in the wrong context. The full working implementation of each approach, including the audit entity schema, scoped service wiring, and a complete test suite, is available on Patreon for teams who want production-ready code alongside the theory.

Understanding Ch 12 of the Zero to Production course walks through audit trail implementation inside a complete ASP.NET Core API, showing how SaveChanges interceptors and domain events work together within the same production codebase — with the infrastructure already wired in.

What Audit Logging Is Actually Solving

Before selecting an approach, it is worth being precise about what you are trying to capture. Enterprise teams typically need audit logging for at least one of three reasons:

• Compliance and regulatory mandates — GDPR, HIPAA, SOC 2, PCI-DSS, and similar frameworks require demonstrable records of who accessed or changed what, and when

• Operational debugging — reconstructing what a user did immediately before a data integrity problem surfaced

• Security forensics — detecting and investigating suspicious access patterns or privilege escalation after the fact

The approach you choose should match the audit signal you actually need. HTTP-level signals are fundamentally different from persistence-level signals, which are different again from business-intent signals. Conflating them leads to audit logs that look impressive and help no one.

Approach 1: Request-Level Middleware

What It Captures

ASP.NET Core middleware sits at the HTTP pipeline level. A custom middleware component can intercept every inbound request and outbound response, capturing the actor identity (from HttpContext.User), the endpoint called, the HTTP verb, the request timestamp, the response status code, and optionally the request body.

Middleware audit logging answers: who called what, when, and what did the API say back?

When Middleware Is the Right Choice

Middleware audit logging is appropriate when:

• You need an HTTP access log independent of whether a database operation succeeded

• Your compliance requirement is specifically about API endpoint access, not data mutation (common in healthcare and financial services where access logs are mandated separately from change logs)

• You are auditing endpoints that use raw SQL, external service calls, or caching — where no EF Core interaction occurs

• You need to capture requests that fail validation and never reach the service layer at all

• Your team wants a consistent audit record regardless of which persistence strategy each endpoint uses

A well-implemented middleware audit log captures the full HTTP story. It does not care whether the underlying operation used EF Core, Dapper, or a third-party API.

When Middleware Is Not the Right Choice

Middleware becomes the wrong tool when:

• You need field-level change tracking (which property changed from what value to what value)

• You are auditing batch operations that issue multiple database writes per HTTP request

• You need to distinguish between business operations at a finer grain than HTTP routes provide

• Your audit store requires transactional consistency with the data change (middleware writes happen outside your database transaction)

The transactional consistency limitation is the most significant. If a middleware component writes the audit record to its own table and the downstream database write then fails and rolls back, you have an audit log entry for an operation that never actually completed. That kind of phantom audit entry can create compliance problems as serious as the missing records it was meant to prevent.

Approach 2: EF Core SaveChanges Interceptors

What It Captures

EF Core interceptors hook into the SaveChanges pipeline. A SaveChangesInterceptor implementation receives the ChangeTracker before persistence, exposing every entity being inserted, updated, or deleted — including the old and new property values for updates.

The ISaveChangesInterceptor interface provides both synchronous and asynchronous interception points, and because it runs inside the same database transaction as your domain changes, the audit record either commits with the data or rolls back with it.

EF Core interceptors answer: what changed in the database, which entity was affected, and what were the before/after values?

When EF Core Interceptors Are the Right Choice

Interceptors are the dominant choice for enterprise audit logging when:

• You need field-level change history with old and new values (mandatory for financial systems, healthcare records, and many GDPR scenarios)

• Transactional consistency between the audit record and the data change is a hard requirement

• Most or all of your persistence goes through EF Core (which is true for the majority of ASP.NET Core APIs)

• You want a low-friction, automatic capture that works across all entities without modifying individual service methods

• You are implementing a general-purpose audit trail for all data mutations, not a curated set of business events

The ChangeTracker gives interceptors complete visibility into what EF Core is about to commit. Combined with ICurrentUserService (or similar) for resolving the actor identity, an interceptor can populate a normalized AuditLog table with virtually no changes to existing business logic.

One important design detail: interceptors run inside the request scope and have access to scoped DI services — but only if you register them correctly. Registering an interceptor that captures a scoped service as a singleton is one of the most common sources of DbContext disposal errors in production audit implementations.

When EF Core Interceptors Are Not the Right Choice

Interceptors fall short when:

• Your API uses Dapper or raw SQL for performance-critical paths — those writes are invisible to the ChangeTracker

• You need to capture business intent, not just field mutations. A property change from Status = Pending to Status = Approved is captured as a raw field update; the fact that it represents an approval decision by a specific role is not

• You use soft deletes widely — the interceptor captures the IsDeleted field flip, not a semantically meaningful "deleted" event

• Your audit requirement is for access patterns (who viewed a record), not just mutations — EF Core read operations do not pass through SaveChanges

The coverage gap matters. If a significant portion of your data access bypasses EF Core, interceptors give you a partial audit log that may appear complete but silently misses entire categories of writes.

Approach 3: Domain Event Handlers

What It Captures

Domain events express what happened in terms the business actually cares about: OrderApproved, UserRoleEscalated, PaymentRefunded, AccountSuspended. When these events are raised by domain entities and handled by dedicated audit handlers, the audit log captures business intent rather than raw data mutations.

Domain event audit handlers answer: what business decision was made, by whom, in what context, and what was the outcome?

When Domain Events Are the Right Choice

Domain events are the superior choice for audit logging when:

• Your compliance requirement demands audit records at the business operation level (common in regulated industries where regulators want to know "who approved this loan" not "who set ApprovalStatus to true")

• You are operating in a domain-rich model (DDD) where entities already raise events for state transitions

• You need audit entries that are interpretable by non-technical reviewers (compliance officers, auditors, legal teams)

• Your audit records feed downstream systems — event sourcing, SIEM platforms, external audit repositories — that expect business-level event payloads

• You use MediatR pipeline behaviors and already have a cross-cutting audit behavior in place

Domain events decouple the audit concern from both HTTP and persistence infrastructure. The audit handler is just another event consumer — it can write to a dedicated audit store, a separate database, an event stream, or a compliance platform without touching the business logic that raised the event.

When Domain Events Are Not the Right Choice

Domain events require investment to be effective. They are not the right primary audit strategy when:

• Your codebase uses an anemic domain model where entities are passive data containers — there are no events to raise

• You need comprehensive coverage of all data mutations, not just curated business state transitions

• You are working with a legacy codebase where introducing domain events requires broad refactoring

• Field-level change history is required — domain events typically carry intent and outcome, not property-level diffs

Relying solely on domain events also creates an inherent coverage risk: a developer adds a new write path without raising the corresponding event, and that write is silently excluded from the audit trail. Interceptors, by contrast, capture everything that flows through EF Core automatically.

Decision Matrix: Which Approach for Which Requirement?

The Layered Strategy: Why Most Production Systems Use Two

The most robust enterprise audit implementations combine approaches rather than picking one. A practical layered strategy for most ASP.NET Core APIs looks like:

1. EF Core interceptor as the default — captures all data mutations automatically with transactional consistency. This is the always-on safety net.

2. Domain events for high-value business operations — OrderPlaced, UserSuspended, PermissionGranted — where compliance or legal teams need interpretable records in business language.

3. Middleware for access auditing — separate from data mutation auditing, handles the "who viewed this endpoint" requirement when regulatory mandates require it.

This layered approach means no single audit mechanism is a single point of failure. If a domain event is accidentally omitted from a new write path, the interceptor still captures the underlying data change. If the EF Core path is bypassed, the HTTP access log still records the attempted operation.

Anti-Patterns to Avoid

Logging audit records outside a transaction. Writing audit entries to a separate table in a different database context (or a different service call entirely) creates phantom audit entries when the main transaction rolls back. Always co-locate your EF Core audit writes in the same DbContext or use a transactional outbox if the audit store is external.

Logging full request bodies everywhere. HTTP middleware that captures raw request bodies will capture PII, passwords, and payment card data unless you apply sensitive field masking. GDPR and PCI-DSS make this a compliance liability, not a feature.

Registering scoped services as singletons in interceptors. EF Core interceptors registered as singletons cannot safely inject scoped services like ICurrentUserService. Use AddInterceptors() at AddDbContext() time with proper scoping, or resolve the current user from IHttpContextAccessor injected at the correct lifetime.

Treating structured logging as an audit log. Application logs (Serilog, OpenTelemetry traces) are for operational visibility. Audit logs are a legal artifact. Using the same storage, format, and retention policy for both is a governance failure. Structured logs rotate and are pruned; audit records must be immutable and retained for defined regulatory periods.

What to Adopt Right Now

For teams building a new ASP.NET Core API or auditing an existing one:

• Start with an EF Core SaveChanges interceptor — it gives immediate, broad coverage with minimal code change

• Add domain events for the 5–10 business operations your compliance team actually asks about in audit reviews

• Add middleware HTTP access logging only if your security or compliance requirement explicitly demands endpoint-level access records

• Review your audit record retention policy and make sure audit tables are protected from application-layer deletes

☕ If this decision guide saved you time, buy us a coffee — it helps keep content like this coming.

FAQ

What is the difference between audit logging and application logging in ASP.NET Core? Application logging (via Serilog, ILogger, OpenTelemetry) records operational events for debugging and observability — log levels rotate, data is pruned, and the format is optimised for developer tooling. Audit logging records legally significant changes to data or access by users — records must be immutable, tamper-evident, and retained for defined compliance periods. Storing both in the same sink under the same retention policy is a compliance risk.

Can EF Core interceptors audit Dapper or raw SQL queries? No. EF Core's SaveChangesInterceptor only observes operations flowing through the EF Core DbContext. Writes executed via Dapper, FormattableString raw SQL outside of EF Core, or direct ADO.NET calls are invisible to the change tracker. If your codebase mixes EF Core with Dapper, your interceptor audit log will be incomplete unless you add explicit audit writes in the Dapper code paths.

Should audit logs be stored in the same database as application data? For most mid-size APIs, co-locating audit tables in the same database is practical and makes transactional consistency straightforward. For high-compliance scenarios (financial, healthcare), a dedicated audit database with write-only application access — so the application can insert but not update or delete audit rows — provides stronger tamper-evidence. The tradeoff is operational complexity.

How do I capture the current user identity inside an EF Core interceptor? Inject IHttpContextAccessor into the interceptor (resolving it from the service provider at AddDbContext time, not as a singleton property). Access httpContextAccessor.HttpContext?.User?.FindFirstValue(ClaimTypes.NameIdentifier) to retrieve the authenticated user ID. If the interceptor runs in a background job context where there is no HTTP context, fall back to a dedicated ICurrentUserService that can return a system identity for non-request-scoped operations.

What fields should every audit log record include? At minimum: entity type, entity primary key, operation type (Insert/Update/Delete), actor identity (user ID or system identity), timestamp (UTC), the changed properties with old and new values (for updates), and a correlation or request ID that ties the audit entry back to the HTTP request. For higher compliance requirements, add the source IP address, session identifier, and a hash of the record for tamper detection.

Is there a performance cost to EF Core SaveChanges interceptors? Yes, but it is typically small relative to the network round-trip cost of the database write itself. The interceptor traverses the change tracker, which is already populated before SaveChanges. The dominant cost is the additional INSERT into the audit table — keep audit writes in the same transaction and batch them when multiple entities change in a single SaveChanges call. Avoid serialising full object graphs to JSON in the hot path; capture only the changed properties.

Do domain events work for audit logging in a CQRS / MediatR setup? Yes, and this is one of the cleaner integration points. A MediatR pipeline behavior can intercept all commands, extract the actor and intent, and publish an audit event after the command handler succeeds. This gives you a consistent audit record for every state-changing command without modifying individual handlers. Combine it with an EF Core interceptor for the field-level detail and you have both business-intent and data-level coverage in the same system.

This checklist gives your team a concrete, ordered reference for configuring the middleware pipeline in any ASP.NET Core application — whether you are working on a minimal API, a controller-based Web API, or a modular monolith. If you want to see the middleware pipeline wired correctly inside a complete, production-grade ASP.NET Core API — alongside CQRS, EF Core, validation, and JWT auth — the Zero to Production course covers the full Program.cs setup in context, so everything is connected from day one.

The full reference implementation — including annotated Program.cs files for both minimal and controller-based APIs, custom middleware samples, and edge-case handling — is available on Patreon, with the source code structured to map directly to what enterprise teams actually ship.

Why Middleware Ordering Matters More Than You Think

Middleware in ASP.NET Core executes as a chain. Each component runs in the order it is registered, processes the request, passes control to the next component, and then runs again on the way back through the response. This bidirectional flow means that a middleware registered after another can never affect how that earlier middleware processes the request — only how it processes the response.

This has real security and correctness consequences:

• Exception handlers registered too late will miss exceptions thrown by earlier middleware

• Authentication registered after routing will fail silently on some routes

• Rate limiting applied before routing cannot partition by endpoint

The checklist below follows the recommended registration order for a production ASP.NET Core API. Each item includes the reasoning, so your team knows why it goes there — not just that it does.

The 12-Point ASP.NET Core Middleware Pipeline Checklist

✅ 1. Exception Handling Goes First — Always

UseExceptionHandler() (or a custom IExceptionHandler implementation for .NET 8+) must be the first middleware registered in the pipeline. It can only catch exceptions thrown by middleware that runs after it. Placing it anywhere else creates a silent blind spot.

In development, UseDeveloperExceptionPage() can replace UseExceptionHandler() to surface stack traces — but never ship it to production.

Why it matters: A middleware registered at position 5 cannot catch an unhandled exception thrown at position 3. The exception propagates past the exception handler entirely.

For a detailed breakdown of how IExceptionHandler differs from traditional exception middleware and when to use each, see 7 Common ASP.NET Core Middleware Mistakes and How to Fix Them.

✅ 2. HSTS and HTTPS Redirection Come Second

UseHsts() and UseHttpsRedirection() belong near the top, after exception handling but before any request-processing middleware. HSTS instructs browsers to only connect over HTTPS for a defined period. HTTPS redirection catches plain HTTP requests and issues a 301 before anything else has a chance to read request data over an unencrypted channel.

Skip UseHsts() in development (it persists in the browser and breaks local HTTP testing). The standard pattern uses an environment check: call UseHsts() only when app.Environment.IsProduction().

✅ 3. Static Files Before Routing and Auth

UseStaticFiles() short-circuits the pipeline for static asset requests. There is no point running routing, authentication, or authorization for a request that just wants site.css. Register it before the routing middleware to keep those requests cheap.

If your API serves no static files, skip this entirely — unnecessary middleware registrations add measurable overhead at scale.

✅ 4. Routing Before Auth and Rate Limiting

UseRouting() must be registered before any middleware that needs to know which endpoint is being targeted. This includes authentication, authorization, rate limiting, CORS, and output caching when you want endpoint-aware policies.

Without routing resolved, middleware like UseRateLimiter() cannot apply per-endpoint policies — it falls back to global policies only, which is usually not what you want.

Note: In .NET 6 and later, UseRouting() is often called implicitly when you call app.MapControllers() or app.MapGet(...). If you rely on implicit routing, be aware that any middleware registered before those calls runs before the route is resolved.

✅ 5. CORS Middleware Before Authentication

UseCors() must be registered before UseAuthentication() and UseAuthorization(). A preflight OPTIONS request from a browser will not carry auth credentials — if your auth middleware runs first and rejects the unauthenticated OPTIONS request with 401, the CORS handshake fails before the browser even sends the real request.

Register the default CORS policy with UseCors() here, or reference a named policy if you have multiple policies configured. Endpoint-level [EnableCors("PolicyName")] attributes still need the global middleware registered in the pipeline.

✅ 6. Authentication Before Authorization — Always

UseAuthentication() populates HttpContext.User from the incoming token or cookie. UseAuthorization() reads HttpContext.User to evaluate policies and roles. If they are swapped, every request arrives at the authorization check with an unauthenticated principal, and [Authorize] attributes silently fail.

This ordering mistake is one of the most common sources of "everything returns 401" bug reports on Stack Overflow. The ASP.NET Core docs are explicit about this ordering, but it is easy to miss in a fast-growing Program.cs.

✅ 7. Rate Limiting After Routing, After Auth (Usually)

UseRateLimiter() should be registered after UseRouting() and typically after UseAuthentication(). This allows you to partition limits by authenticated user identity (e.g., per-user or per-subscription-tier policies) rather than just by IP address — which is far more meaningful for most APIs.

If you only need IP-based rate limiting and want it as a pure traffic filter before any app logic runs, you can move it earlier — but you lose the ability to read user claims for partitioning.

✅ 8. Output Caching After Auth, Before Endpoint Middleware

UseOutputCaching() should run after UseAuthentication() and UseAuthorization(), so that cached responses are only served for requests that have already been authorized. Caching authenticated responses before authorization is checked can serve one user's data to another.

Tag-based invalidation, vary-by-query, and vary-by-header policies should be configured at registration time using AddOutputCache() in the service collection, then referenced by name at the endpoint level via [OutputCache(PolicyName = "...")].

✅ 9. Custom Middleware in the Right Place

Custom middleware components — correlation ID injection, request logging, tenant resolution, feature flag evaluation — need to be placed deliberately:

• Correlation ID / request context: Register early, after exception handling, so the correlation ID is available in all subsequent log entries including error logs

• Tenant resolution: Register after routing (so the route is known) but before any data access middleware that needs the tenant context

• Request/response logging: Register early but after exception handling, so the logger captures both successful and error responses

• Feature flags: Register after routing and auth if the flag check is per-user; register before routing if it is a kill-switch for the entire endpoint

The rule: place custom middleware where it can see everything it needs from earlier middleware and affect everything that runs after it.

✅ 10. Map Endpoints Last

app.MapControllers(), app.MapGet(...), app.MapHub(...), and similar calls should come at the end of the pipeline configuration. These define the terminal middleware — the actual endpoints that handle the request. Everything registered before them acts as a pipeline gate or cross-cutting concern.

Adding a middleware after app.MapControllers() has no effect on controller requests because the request has already been handled before the middleware has a chance to run on the inbound path.

✅ 11. Review Your Program.cs After Every Major Dependency Addition

Every time your team adds a new NuGet package that registers middleware (rate limiting libraries, telemetry SDKs, feature flag providers, API gateway SDKs), the package documentation may specify a required registration order. Blindly appending app.UseNewThing() at the bottom is a common source of subtle bugs.

Make it a habit to review the full middleware registration sequence in code review. If your team uses a code review checklist, add middleware ordering as a line item.

✅ 12. Audit Against the Recommended Pipeline for Your Scenario

Microsoft publishes a canonical recommended middleware order for different application types. The most common one for Web APIs is:

1. UseExceptionHandler / UseDeveloperExceptionPage

2. UseHsts

3. UseHttpsRedirection

4. UseStaticFiles

5. UseRouting

6. UseCors

7. UseAuthentication

8. UseAuthorization

9. UseRateLimiter

10. UseOutputCaching

11. MapControllers / MapGet / endpoint mapping

Compare your Program.cs against this sequence regularly — especially after refactoring or upgrading major framework versions. For a broader view of what a production-ready ASP.NET Core API needs beyond middleware, see The 12-Point ASP.NET Core Production Readiness Checklist for .NET Teams.

The Items Teams Get Wrong Most Often

Based on the patterns we see repeatedly, these three items cause the most production incidents:

Exception handler registered too late — Registering UseExceptionHandler() after authentication means auth exceptions (like invalid token signatures or expired tokens from the JWT bearer handler) propagate unhandled and return a plain 500 with no ProblemDetails body.

CORS registered after authentication — Browser preflight requests fail with 401 before the CORS handshake completes, causing the client to see a confusing CORS error when the real issue is middleware order.

Rate limiting placed before routing — IP-based limits work, but per-user partitioning silently falls back to anonymous handling because the user identity is not yet available. The limits appear to apply, but the partitioning logic never fires.

What About IMiddleware vs RequestDelegate?

If your team writes custom middleware, prefer the IMiddleware interface (registered with AddTransient<T>() in the service collection) over the convention-based RequestDelegate approach for any middleware that takes dependencies. IMiddleware gets its dependencies from DI on each request, making it scoped-safe. Convention-based middleware receives its dependencies in the constructor, which means they are resolved once at startup — creating the classic captive dependency problem for scoped services.

For a complete reference on the idempotency middleware pattern in ASP.NET Core — including the full source code — the dotnet-api-idempotency-middleware repo shows how a production-grade custom middleware handles dependency injection, request body hashing, and distributed cache integration.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What is the correct middleware order in ASP.NET Core?

The recommended order for a Web API is: exception handling first, then HSTS and HTTPS redirection, static files, routing, CORS, authentication, authorization, rate limiting, output caching, and finally endpoint mapping. This order ensures each component has access to the context it needs and that security gates run before business logic.

Why must UseAuthentication come before UseAuthorization?

UseAuthentication populates HttpContext.User by validating the incoming token or cookie. UseAuthorization reads HttpContext.User to evaluate policies. If authorization runs first, it reads an empty or unauthenticated principal and rejects the request with 401, regardless of whether the credentials in the request are valid.

Why does CORS need to be registered before authentication?

Browser preflight (OPTIONS) requests do not carry credentials. If authentication middleware runs before CORS and rejects the unauthenticated OPTIONS request, the browser never receives the CORS headers it needs to proceed, causing a CORS error on the client — even though the actual request would have been authorised.

Can I register rate limiting before authentication in ASP.NET Core?

You can, but with a trade-off. Rate limiting before authentication can only partition by IP address or other request properties. If you need per-user or per-subscription-tier limits, rate limiting must run after authentication so it can read user identity from HttpContext.User.

Does middleware order matter for output caching?

Yes. Output caching should run after authentication and authorization to avoid serving a cached authenticated response to a different user. If caching runs before the auth check, a response cached for user A could be returned to user B on the next matching request.

What happens if I register a middleware after MapControllers()?

Middleware registered after MapControllers() will never execute on the inbound request path for controller actions, because MapControllers() defines the terminal middleware. The request is handled before the later-registered middleware runs inbound. Any code you intended to run as pre-processing will be silently skipped.

How do I debug middleware ordering issues in development?

Use the Microsoft.AspNetCore.MiddlewareAnalysis NuGet package in development. It logs each middleware component in pipeline order with its execution timing, making it easy to see both the ordering and where a request is short-circuited. Pair this with structured logging using Serilog's UseSerilogRequestLogging() to capture the full request lifecycle in your development logs.

Seeing filtering and sorting work in isolation is useful. Understanding how they compose with EF Core queries, pagination wrappers, and IQueryable chaining inside a complete production API is what separates a working prototype from a production-ready codebase. Chapter 4 of the Zero to Production course covers exactly this — filtering, sorting, and cursor-based pagination all wired together in the same codebase.

What These Libraries Actually Solve

Before reaching for any library, it helps to understand what problem they are all solving at the same level. A client hits GET /products?name=widget&price>10&sort=name&page=2&pageSize=25. Somewhere in your API, you need to:

1. Parse the query string into filtering predicates

2. Translate those predicates into an IQueryable expression tree

3. Apply a sort order to the same query

4. Apply Skip and Take for pagination

All three libraries — Sieve, Gridify, and OData — handle this pipeline. They differ in how much control the client gets, how much configuration the developer must provide, and what the API contract looks like.

Sieve: Attribute-Driven, Explicit Control

Sieve takes a developer-first approach. You explicitly mark which properties on your domain entities are filterable and sortable using [Sieve(CanFilter = true, CanSort = true)] attributes. Nothing is filterable unless you explicitly opt in.

The query string convention is simple: ?filters=Name@=Widget&sorts=Price&page=1&pageSize=20. The @= operator is a case-insensitive contains, == is exact match, > and < are range operators. The client gets a well-defined, intentional surface.

What Sieve does well:

• The attribute approach means the server is always in control. A client cannot filter on a field you have not marked — there is no accidental data leakage through queries.

• Works cleanly with EF Core IQueryable — the filtering, sorting, and pagination all run database-side before materialisation.

• The operator syntax is readable and easy to document. ?filters=Status==Active,CreatedAt>2026-01-01 reads clearly.

• Custom sort/filter logic is supported via override methods in a custom SieveProcessor.

• The library is mature, well-tested, and the Biarity/Sieve GitHub repository has been the standard reference for this pattern in the .NET ecosystem for years.

Where Sieve shows friction:

• The attribute approach has a hidden cost: your domain entities start carrying infrastructure concerns. If you care about keeping your domain layer clean, decorating entity properties with [Sieve] attributes feels like a leak. You can work around this using a fluent configuration override, but it adds setup.

• Multi-tenant scenarios where different clients should see different filterable fields require custom processors.

• The library's maintainer has had periods of low activity — check the issue tracker before committing to it in a long-lived codebase.

• Complex nested filtering (filtering on a child collection's property) requires custom handling.

When to reach for Sieve:

• You want a simple, explicit opt-in model

• The team is comfortable decorating entities with attributes

• API clients are mostly internal and the query surface is predictable

• You want tight control over what is exposed via query parameters

Gridify: Fast, Convention-Based, LINQ-First

Gridify takes a different stance. It is a lightweight library that parses a filtering string expression into an IQueryable<T> expression tree dynamically, without requiring attribute decorations on your entities. The client sends ?filter=name=Widget AND price>10&orderBy=name asc&page=2&pageSize=25.

The parsing is expression-tree based, which keeps it close to native LINQ performance. Independent benchmarks on the Gridify documentation show it operating near the speed of a hand-written LINQ expression for common filter operations — a meaningful advantage over reflection-heavy alternatives.

What Gridify does well:

• Zero attribute decoration required — works against any POCO, DTO, or entity

• Clean expression-tree compilation means the filtering translates directly to SQL via EF Core with no N+1 risks

• The filter syntax is natural and client-friendly: name=Widget AND price>10 OR category=Electronics

• Mapper classes (GridifyMapper<T>) let you define which fields are mappable without touching entity classes — keeping domain and API surface separate

• Actively maintained (alirezanet/Gridify on GitHub) with regular releases

Where Gridify shows friction:

• The filter syntax (name=Widget AND price>10) is more expressive than Sieve, which is a double-edged sword — more powerful queries also means a larger attack surface if you are not careful about what is exposed through the mapper

• Documentation for advanced scenarios (nested relationships, custom type converters) is thinner than Sieve

• The default behaviour allows filtering on all public properties of the target type unless you explicitly configure a mapper — the inverse of Sieve's opt-in model

When to reach for Gridify:

• You want clean entity classes without attribute decoration

• Performance is a priority and you want expression-tree-compiled filters

• API clients need a flexible, expressive filter syntax

• The team already works with DTOs as the query surface (not raw entities)

OData: Protocol-Level, Maximum Power, Maximum Overhead

OData is not a library — it is a standardised protocol for building queryable APIs. The ASP.NET Core implementation (Microsoft.AspNetCore.OData) exposes the full OData query specification: \(filter, \)orderby, \(select, \)expand, \(top, \)skip, $count.

What this buys you is enormous power: clients can select individual fields, expand navigation properties (joins), apply nested filters on related entities, and get precise metadata about the query result. Tooling in Power BI, Excel, and enterprise reporting suites understand OData natively.

What OData does well:

• The most capable query language of the three — clients can express queries that would require multiple round-trips with the other libraries

• $expand enables client-side relationship traversal without building custom endpoints

• Native tooling integration — BI tools, Excel data connections, and enterprise integration platforms understand OData out of the box

• Standardised, versioned protocol — behaviour is documented, predictable, and not library-specific

• The Microsoft OData library for ASP.NET Core is production-grade and maintained by the OData team

Where OData shows friction:

• Adds significant API surface area. A poorly configured OData endpoint can expose more of your data model than intended.

• The $expand feature can generate expensive database queries if Eager Loading is not carefully controlled

• OData's EDM (Entity Data Model) setup requires non-trivial configuration and tightly couples your API to your EF Core model

• Response envelopes change shape (OData wraps results in @odata.context, value, etc.) — clients and tests must handle this format

• For most public REST APIs, OData is far more than what is needed and the overhead shows in onboarding cost

• The learning curve is steep. Senior engineers encountering OData for the first time still take meaningful time to understand \(metadata, \)expand semantics, and query validation configuration

When OData makes sense:

• Internal enterprise APIs consumed by BI tools, Power BI, or Excel

• APIs that need to support ad-hoc querying from non-developer consumers

• Integration scenarios where OData compatibility is a hard requirement

Side-by-Side Comparison

Does Your ASP.NET Core API Need a Library at All?

What Is the Best Approach for Filtering in ASP.NET Core?

For small APIs with three to five filterable endpoints, hand-rolled IQueryable filtering is perfectly reasonable. A typed ProductQueryParams record with explicit filter properties — price range, category, name — gives you full control with zero dependency. The cost shows up at scale: fifteen endpoints, fifty filterable fields, and inconsistent query string conventions across the team.

At that point, a library removes the duplication, standardises the query contract, and keeps individual endpoints focused on authorisation and business logic rather than filter plumbing.

The Clear Winner for Most Teams

Sieve is the right default for teams building internal or semi-public REST APIs where you want deliberate, audited control over what is filterable. The attribute model is explicit — every filterable field is a conscious decision.

Gridify is the better choice when entity cleanliness matters, performance is a priority, or API clients need an expressive filter syntax. The mapper pattern keeps your domain layer free of infrastructure concerns while still giving you tight control.

OData is the right call only when enterprise tooling integration is a hard requirement or you are building an internal data API consumed by BI tools. For most REST APIs, OData is significant overhead for a problem that Sieve or Gridify solve more cleanly.

The recommendation: start with Gridify for new projects. The mapper pattern scales cleanly, the syntax is intuitive, and the near-native performance means you are not paying a penalty as query complexity grows. Switch to Sieve if your team strongly prefers the attribute-based opt-in model. Only reach for OData when the enterprise tooling requirement is explicit.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

Is Sieve still actively maintained in 2026? The core library (Biarity/Sieve) has had periods of reduced activity. The fundamentals are stable but check the GitHub issue tracker for any recent .NET version compatibility concerns before committing to a new project. Community forks are available if the primary repo falls behind.

Can Gridify be used safely with EF Core without causing N+1 queries? Yes — Gridify generates expression trees that EF Core translates directly to SQL. Filtering, sorting, and pagination all execute server-side before materialisation. The key is to ensure you are passing an IQueryable<T> (not an IEnumerable<T>) to the Gridify processor, so no premature client-side evaluation occurs.

Does OData work with Minimal APIs in ASP.NET Core? OData support in ASP.NET Core historically required Controllers and was not compatible with Minimal APIs. As of recent Microsoft.AspNetCore.OData releases, partial support has been added, but the integration is not as clean as with controller-based APIs. For OData use cases, Controllers remain the more reliable choice.

What is the difference between Sieve's @= operator and ==?== is an exact match (case-sensitive by default, configurable). @= is a case-insensitive contains — equivalent to LIKE '%value%' in SQL. Sieve also supports _= (starts with), =@ (ends with), and _-= (case-insensitive starts with), giving clients a useful range of string matching without exposing raw SQL.

Can I use Sieve or Gridify with non-EF Core data sources? Both libraries work against any IQueryable<T> implementation. In practice, you can use them with Dapper by materialising data to a list first, but you lose the database-side execution benefit — filtering will happen in memory. For non-relational or non-IQueryable data sources, manual filtering logic is often the better trade-off.

Which library handles multi-column sorting best? All three support multi-column sorting. Sieve uses a comma-separated sorts parameter (?sorts=Name,-Price where - prefix means descending). Gridify uses ?orderBy=Name asc, Price desc. OData uses ?$orderby=Name asc, Price desc. Gridify's syntax is arguably the most readable for multi-column cases.

Is Gridify's filter syntax safe from injection attacks? Gridify parses filter strings into expression trees — it does not produce raw SQL strings. The expression tree is passed to the LINQ provider, which handles parameterisation. As long as you are using a mapper to restrict which properties are queryable, there is no SQL injection risk. Always define a GridifyMapper<T> rather than relying on the default open mapping.

If you want to see how these patterns work inside a complete production-grade ASP.NET Core codebase — with pipeline behaviors, background processing stages, and all of it wired together — the full implementation is available on Patreon, with annotated source code that maps directly to what enterprise teams actually ship.

Understanding processing pipelines in isolation is useful — seeing them as part of a complete production API alongside CQRS, Clean Architecture, and background task orchestration is what makes the design decisions click. That is exactly what Chapter 12 of the ASP.NET Core Web API: Zero to Production course covers — with source code you can run immediately.

What Problem Does the Pipes and Filters Pattern Solve?

The Pipes and Filters pattern structures a processing task as a sequence of independent, composable stages — each stage (a filter) receives input, transforms or evaluates it, and passes the result to the next stage via a pipe. No stage needs to know about the stages before or after it. Each stage has a single, well-defined responsibility.

The pattern addresses a recurring problem: when a task involves multiple distinct processing steps that can be independently tested, reordered, enabled, or replaced without the other steps knowing. Tangled, monolithic service methods that do validation, enrichment, transformation, and persistence in one continuous flow are the symptom this pattern is designed to fix.

In ASP.NET Core, the middleware pipeline is a first-class, built-in implementation of Pipes and Filters. Every Use, UseWhen, or Map call registers a filter. The request flows through them in registration order. Each middleware calls next() to pass control downstream and can act again on the way back. That is the pattern — applied at the HTTP layer.

The Two Faces of Pipes and Filters in .NET

In practice, the pattern shows up in two distinct forms inside .NET applications.

The Request Pipeline (Framework-Level)

ASP.NET Core's IMiddleware and RequestDelegate chain are the canonical implementation. The framework owns the pipe; you implement the filters. You add cross-cutting concerns — authentication, rate limiting, correlation ID propagation, exception handling — as discrete middleware components.

The filter in this context is IMiddleware or the convention-based InvokeAsync(HttpContext context, RequestDelegate next) signature. Each component has access to HttpContext, can short-circuit the pipeline (by not calling next), and can observe or modify both the request and the response.

Custom Domain Pipelines (Application-Level)

The second form appears when you build your own pipeline for domain-level processing: a document ingestion flow that validates → enriches → classifies → persists; a payment workflow that checks limits → applies fraud rules → calls the processor → emits an event; a data transformation chain that normalises → validates → maps → stores.

Here you implement the pipe yourself, and MediatR's IPipelineBehavior<TRequest, TResponse> is the most natural way to do it in a Clean Architecture + CQRS setup. Each behavior is a filter; MediatR is the pipe. System.Threading.Channels serves the same role in producer-consumer processing loops where you need backpressure, concurrency control, and stage isolation.

When to Use the Pipes and Filters Pattern

Apply the pattern when the following conditions hold:

The task has multiple distinct stages. If a single service method performs validation, enrichment, transformation, and persistence as one sequential block, each step is an implicit filter. Making them explicit — and decoupled — yields components you can test independently and reorder without side effects.

Stages have different operational characteristics. Some stages are CPU-bound (parsing, hashing), others are I/O-bound (database writes, external API calls), others are stateless (validation). When stages differ in latency profile, error handling strategy, or retry policy, separating them into discrete components lets you apply the right operational model to each.

The pipeline needs to evolve without coordinated changes. New business requirements often mean new stages — a compliance check, a new enrichment source, an audit event. A Pipes and Filters structure absorbs new stages at the insertion point without modifying the existing stages around them.

Cross-cutting concerns must not bleed into business logic. Logging, correlation tracking, caching, validation, and performance measurement belong in the pipeline, not in the handlers. Pipeline behaviors (MediatR) and middleware (ASP.NET Core) enforce this boundary structurally — it is architecturally impossible for a handler to skip the logging behavior if the behavior wraps every command.

Stages can be reused across multiple pipelines. A fraud-check stage that reads from a shared rules engine, or a normalisation stage that applies canonical formatting, should be written once and composed into any pipeline that needs it — not copy-pasted.

When Not to Use It

The pattern introduces indirection. When that indirection does not pay off, avoid it.

When the task is genuinely simple. A CRUD endpoint that reads from the database and returns a DTO does not benefit from a four-stage pipeline. The overhead of designing, naming, and wiring discrete stages is not justified for straightforward transformations.

When stages are tightly coupled by shared state. Pipes and Filters works because each stage is independent. If your stages share a mutable context object that grows as it passes through, you have a different pattern — the Chain of Responsibility or a workflow engine — and you should name it as such.

When ordering is non-trivial and frequently changes. If stage ordering has complex conditional logic ("run stage B only after stage A, but only if stage C did not short-circuit"), you are describing an orchestrated workflow, not a linear pipeline. A workflow engine or saga handles that more explicitly.

When you need guaranteed stage isolation in distributed systems. A single-process MediatR pipeline shares the same process and transaction scope. If stages genuinely need to run in separate services, survive process restarts independently, or scale independently, the Competing Consumers or Saga patterns are more appropriate.

How the Pattern Is Expressed in ASP.NET Core

Middleware as Pipes and Filters

The simplest expression of the pattern in ASP.NET Core is the middleware pipeline registered in Program.cs. The registration order is the execution order. Short-circuiting is explicit: a middleware that does not call next terminates the pipeline at that stage.

The key design principle here is the single-responsibility constraint on each component. A rate limiting middleware should do exactly that — apply a rate limit — and nothing else. If it starts checking authentication state to decide whether to rate limit differently, it has absorbed a concern that belongs in a dedicated component earlier or later in the pipeline.

MediatR Pipeline Behaviors

For application-layer pipelines, IPipelineBehavior<TRequest, TResponse> is the idiomatic filter interface. Validation behavior, logging behavior, caching behavior, and transaction behavior all implement this interface. MediatR resolves them in dependency injection registration order and executes them before invoking the handler.

The important constraint: pipeline behaviors should be generic where possible. A ValidationBehavior<TRequest, TResponse> that invokes all registered IValidator<TRequest> instances from DI is a reusable filter for every command and query in the application. A behavior written to handle only one specific request type is not a pipeline behavior — it is business logic that belongs in the handler.

System.Threading.Channels for Async Stage Pipelines

When stages need to process work asynchronously with backpressure, concurrency limits, and stage-local consumers, System.Threading.Channels models the pipe explicitly. Each stage reads from one channel and writes to the next. BoundedChannel provides the backpressure mechanism — if a downstream stage is slow, the bounded buffer prevents unbounded memory growth upstream.

This form is appropriate for document ingestion, event stream processing, or any fan-in/fan-out processing requirement where MediatR's synchronous (per-request) model would create blocking or excessive thread contention.

Trade-offs and Anti-Patterns

The Trade-offs

Anti-Patterns to Avoid

The God Filter. A pipeline behavior or middleware that handles validation, enrichment, caching, and audit logging in a single class. It is indistinguishable from a monolithic service method, just with different plumbing.

Hidden side effects between stages. Stages that write to ambient state — a shared dictionary on the context, a ThreadLocal, an unscoped service — create invisible ordering dependencies. If stage B fails because stage A did not populate a key on a shared object, the pipeline is coupled in ways the type system cannot express.

Overusing the middleware pipeline for business logic. UseWhen and conditional middleware are powerful, but complex branching in Program.cs is a sign that the logic belongs in application-layer handlers, not in the HTTP pipeline. The middleware pipeline should deal with infrastructure concerns. Business rules belong in MediatR handlers and domain models.

Ignoring the ordering contract. AddAuthentication and UseAuthentication must precede UseAuthorization. UseRouting must precede UseEndpoints. The middleware pipeline has implicit ordering contracts that are not enforced by the compiler. Violating them produces bugs that only appear in production under specific conditions. Document the required ordering explicitly in a comment on the registration block.

Decision Matrix

What to Do with Existing Code

If you have a large service class with tangled validation, enrichment, and persistence logic, refactoring to an explicit pipeline is a good investment — but do it in stages.

Start by extracting cross-cutting concerns into MediatR behaviors. Validation is the easiest first step. A ValidationBehavior applied globally immediately removes validation code from every handler and makes the constraint explicit and reusable.

Next, identify the stages hidden inside your handlers. If a handler fetches an entity, applies a business rule, raises a domain event, and saves — those are four stages, three of which (fetch, raise event, save) are infrastructure-layer concerns that belong in behaviors or event handlers, not mixed with the business rule itself.

Use System.Threading.Channels only when you have a genuine async processing requirement with observable backpressure needs. Do not introduce channel-based pipelines as a default architecture — they carry significant operational complexity and are worth it only when the concurrency and backpressure semantics are genuinely needed.

Internal to Coding Droplets, we have written about the related 7 Common ASP.NET Core Middleware Mistakes and How to Fix Them and the CQRS and MediatR in ASP.NET Core: Enterprise Decision Guide — both worth reading alongside this guide for a complete picture of pipeline design in .NET.

For the authoritative reference on the pattern's theory, the Pipes and Filters pattern on the Azure Architecture Center is the canonical starting point, and Microsoft's ASP.NET Core Middleware documentation covers the framework implementation in depth.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What is the Pipes and Filters pattern in ASP.NET Core? The Pipes and Filters pattern structures a processing task as a sequence of independent stages connected by pipes. In ASP.NET Core, the middleware pipeline is the built-in implementation at the HTTP layer. At the application layer, MediatR pipeline behaviors implement the same pattern for command and query processing.

How is the Pipes and Filters pattern different from the Chain of Responsibility? Chain of Responsibility passes a request through handlers where each handler decides whether to process it or forward it — typically only one handler acts. Pipes and Filters passes data through all stages sequentially, with each stage performing its own transformation or evaluation. In ASP.NET Core middleware, both handlers and short-circuiting middleware both exist, but the overall structure is Pipes and Filters.

When should I use MediatR pipeline behaviors vs ASP.NET Core middleware? Use ASP.NET Core middleware for HTTP-level infrastructure concerns — authentication, rate limiting, CORS, exception handling, compression, and request/response logging at the transport level. Use MediatR pipeline behaviors for application-layer cross-cutting concerns — validation, caching, transaction scope, and audit logging at the business operation level. The key signal: if the concern requires knowledge of HttpContext, it belongs in middleware; if it requires knowledge of the command or query type, it belongs in a pipeline behavior.

Can I build custom Pipes and Filters pipelines without MediatR? Yes. The pattern does not require a framework. A simple interface such as IPipelineFilter<T> with an Execute(T context, Func<T, Task> next) signature, combined with a builder that chains filters in registration order, is sufficient. MediatR provides this out of the box for CQRS workloads, and System.Threading.Channels provides it for async producer-consumer flows. For lightweight scenarios, a hand-rolled pipeline with no third-party dependency is a reasonable choice.

How does the Pipes and Filters pattern affect testability? It significantly improves testability. Each filter or behavior can be tested in isolation with a unit test. A validation behavior needs only a set of validators and a fake next delegate. A middleware component needs only an HttpContext and a RequestDelegate. There is no need to construct the entire pipeline to test a single stage — which contrasts sharply with monolithic service methods where a test must trigger all logic simultaneously.

What is the right number of stages in a pipeline? There is no fixed answer, but a useful heuristic: each stage should have a name that clearly describes its single responsibility. If you cannot name a stage without using "and", split it. In practice, MediatR pipelines with three to six behaviors (logging, validation, caching, transaction, error handling, audit) are common in production systems. Middleware pipelines in ASP.NET Core often have ten or more components — each provided either by the framework or as a named, composable component.

Should I use System.Threading.Channels or a message broker for stage pipelines? Use System.Threading.Channels when all stages run in the same process and you need in-process backpressure, concurrency control, and stage isolation without external dependencies. Use a message broker (RabbitMQ, Azure Service Bus, Kafka) when stages need to run in separate processes or services, survive process restarts independently, or scale horizontally at the stage level. Channels are an in-process primitive; brokers are distributed infrastructure. Do not reach for a broker to solve a problem that BoundedChannel<T> handles in ten lines.

Understanding why IMemoryCache does not protect you from this by default, and knowing the exact fix to apply, is the difference between a cache that helps in production and one that creates a new category of failure. The full working implementation — including the SemaphoreSlim locking pattern, the HybridCache migration, and a load test harness you can run against your own API — is on Patreon, with production-ready source code that maps directly to real enterprise workloads.

If you want to see this problem and its fix in context of a complete production API — alongside rate limiting, EF Core, and authentication all wired together — Chapter 9 of the ASP.NET Core Web API: Zero to Production course covers exactly this, including how caching decisions interact with resilience and database access patterns.

What Is a Cache Stampede?

A cache stampede — also called a thundering herd or cache miss avalanche — occurs when multiple concurrent requests all find that a cached value has expired at the same time. Because the value is gone, every one of those requests independently concludes that it needs to regenerate it. They all go to the data source simultaneously. The data source (your database, your downstream API) receives a burst of identical queries that far exceeds what the cache was designed to absorb.

The pattern repeats on every expiry cycle. Instead of one database call every five minutes, you get two hundred simultaneous calls every five minutes, each of which takes longer than usual because the database is now under abnormal load.

In ASP.NET Core, this happens specifically because IMemoryCache.GetOrCreateAsync does not serialize concurrent population. When ten requests call it for the same missing key at the same instant, all ten enter the factory delegate. The cache is not wrong — it is doing exactly what it was designed to do. The problem is the assumption that only one caller will ever enter the factory for a given key at a given time.

Why It Happens in Production but Not Locally

Local testing rarely reveals this problem because developers typically test with low concurrency. One request runs, populates the cache, and the next request hits the populated entry. The race condition requires multiple concurrent callers and an expired (or absent) cache entry to trigger.

In production, three things combine to make it visible:

Traffic shape. High-traffic APIs receive tens or hundreds of requests per second. When a popular cache entry expires, many of those in-flight requests will call GetOrCreateAsync before any of them finishes populating it.

Cache TTL alignment. When all entries for a given category share the same TTL, they expire at the same wall-clock time. A cache warm-up at startup, followed by a fixed absolute expiration, produces synchronized expiry across the cluster.

Slow factory delegates. The longer the factory takes to run — a complex query, a downstream API call, an EF Core join — the wider the window during which concurrent callers can pile in. A factory that takes 200ms under normal load can collect 40 concurrent callers before the first one finishes.

How to Diagnose a Cache Stampede

Before reaching for a fix, confirm you are actually dealing with a stampede rather than a different caching problem.

What to look for in your metrics and logs:

• A periodic spike in database query count that coincides with your cache TTL interval

• Response latency spikes that are narrow (seconds, not minutes) and repeat at a predictable interval

• Structured log entries showing the same cache key being "populated" by multiple concurrent requests within milliseconds of each other

• Database CPU spikes that are correlated with specific cache keys rather than random query patterns

A quick diagnostic approach: add structured logging inside your factory delegate that includes the cache key and a timestamp. If you see the same key logged multiple times within a single second, you have confirmed a stampede. With Serilog and named placeholders, a single log line is sufficient: _logger.LogInformation("Cache miss for key {CacheKey} at {UtcNow}", key, DateTime.UtcNow).

If you are already using IDistributedCache, you may not notice the problem at first because the distributed cache serializes writes differently — but the same fundamental issue can occur if your factory is slow enough and traffic is high enough.

Fix 1: SemaphoreSlim Per-Key Locking

The most widely used fix for IMemoryCache is a SemaphoreSlim that gates entry into the factory delegate. Only one caller is allowed to populate a given key. All other callers wait, and once the first caller finishes and populates the cache, the waiting callers retrieve the value without calling the factory themselves.

The implementation pattern wraps GetOrCreateAsync inside a lightweight keyed lock. The lock is typically stored in a ConcurrentDictionary<string, SemaphoreSlim> so that different keys can proceed concurrently — only callers requesting the same key are serialized.

This approach is effective and works without any dependency changes. The trade-off is added complexity: the lock dictionary must be managed carefully to avoid memory leaks (remove entries after use), and the per-key semaphore adds a small allocation cost on cache miss.

The pattern is most appropriate when:

• You are on .NET 8 or earlier and cannot yet adopt HybridCache

• Your cache usage is concentrated on a small, known set of high-contention keys

• You want precise control over the locking behaviour

Fix 2: Staggered TTL to Break Synchronized Expiry

A simpler partial mitigation is to add a random jitter to the cache TTL. Instead of all entries for a category expiring at exactly the same time, they expire within a window — say, between 4 and 6 minutes for a 5-minute target TTL. This distributes the stampede load over time rather than eliminating it entirely.

Jitter is easy to add: TimeSpan.FromMinutes(5) + TimeSpan.FromSeconds(Random.Shared.Next(0, 60)). The Random.Shared instance in .NET 6 and later is thread-safe.

Staggered TTL does not eliminate the problem — it reduces its impact. Under very high concurrency, even a 60-second jitter window will still produce small stampedes. It is best used as a complementary technique alongside one of the serialization approaches.

Fix 3: HybridCache — Stampede Protection Built In

The cleanest long-term fix for .NET 9 and .NET 10 projects is HybridCache, which was introduced as GA in .NET 9. HybridCache has stampede protection built into its design: it serializes concurrent requests for the same key using a coalescing mechanism. When multiple requests arrive for a missing key simultaneously, only one factory invocation is triggered. The other callers wait for that single result and share it.

This is a first-class guarantee in the API contract, not a workaround. Switching from IMemoryCache.GetOrCreateAsync to HybridCache.GetOrCreateAsync with the same factory delegate gives you stampede protection without any additional locking code.

HybridCache also provides an optional two-layer architecture: a fast in-process L1 cache backed by a distributed L2 (Redis, for example). For multi-instance APIs, the L1+L2 combination means that even after a pod restart, the newly started instance can warm from the shared L2 rather than hitting the database. This directly reduces the window during which a stampede can form.

When to use HybridCache vs the SemaphoreSlim approach:

• New projects on .NET 9 or .NET 10: default to HybridCache

• Existing projects still on .NET 8: the SemaphoreSlim pattern is the right in-place fix

• Multi-instance deployments where L2 (Redis) is already in place: HybridCache provides the most complete solution

Is There a Question About Which Cache to Use?

If the stampede is severe enough that you are investigating this as a production incident, the answer for most teams is: migrate the affected endpoints to HybridCache if you are on .NET 9+. The API surface is close enough to IMemoryCache that a targeted migration of just the high-traffic keys is low-risk and can be done without touching the rest of the codebase.

If you are on .NET 8 or need a fix today without a version upgrade, the SemaphoreSlim pattern is production-proven and straightforward. The risk is that you are now maintaining custom locking infrastructure. Keep it simple: one semaphore per key, clean up after use, and log when the lock is contended.

The one pattern to avoid entirely is using a single global lock across all keys. A wide lock serializes all cache operations and eliminates the concurrency benefits of caching. The whole point of the fix is to serialize per-key, not per-cache.

For a full production-ready implementation — including how the lock dictionary is managed, how the HybridCache migration looks in a real API with Redis as L2, and load test results showing the before and after — the complete source code is at github.com/codingdroplets/dotnet-hybridcache-aspnetcore.

Preventing It From Recurring

Once the immediate fix is in place, the following practices reduce the risk of encountering this again:

Add expiry jitter by default. Make random TTL offset a team convention rather than a case-by-case addition. A helper extension method that wraps IMemoryCache.Set with built-in jitter ensures it is never forgotten.

Monitor per-key cache miss rate. Most observability platforms (Application Insights, Grafana, Seq) can be configured to alert when a specific cache key experiences a sustained elevated miss rate. A miss rate spike is an early warning of a developing stampede.

Use HybridCache for all new high-traffic cache points. Retrofit is cheap — the API is similar to IMemoryCache. There is no reason to write new stampede-vulnerable code on .NET 9+.

Review factory delegate latency. The faster the factory, the narrower the stampede window. Queries inside factory delegates should use AsNoTracking(), return only the columns needed, and have appropriate indexes. A 10ms factory has a much smaller blast radius than a 300ms one.

Load test expiry behaviour explicitly. Add a load test scenario that fires a burst of concurrent requests at a key that has just expired. This is the exact condition that triggers a stampede and it is trivially reproducible under controlled conditions. Catch it before production does.

☕ Found this useful? Buy us a coffee — every bit helps keep the content coming!

FAQ

Does IMemoryCache.GetOrCreate (non-async) have the same stampede problem? Yes. The synchronous GetOrCreate method has the same race condition: multiple callers can enter the factory delegate concurrently for a missing key. The same SemaphoreSlim pattern applies, using SemaphoreSlim.Wait and Release instead of the async equivalents. For new code, prefer the async path to avoid blocking ThreadPool threads.

Will switching to Redis distributed cache fix the stampede? Not automatically. IDistributedCache has the same absence of per-key serialization as IMemoryCache. Multiple instances of your API can still race to populate the same key in Redis simultaneously. The fix — SemaphoreSlim or HybridCache — is needed regardless of which backing store you use. HybridCache with Redis as L2 does protect against this, because stampede coalescing happens at the HybridCache layer.

How many concurrent requests does it take to trigger a stampede? There is no fixed threshold. A stampede can form with as few as two concurrent callers if the factory delegate is slow enough. In practice, stampedes become operationally significant when the factory takes more than 50ms and more than 10 concurrent callers are hitting the same key simultaneously. High-traffic endpoints with expensive factories are the highest risk.

Can output caching be used instead? Output caching caches the full HTTP response at the middleware layer rather than at the service layer. It has stampede protection built in and is a valid alternative for read-only endpoints that return the same response to all callers. It is not a substitute for IMemoryCache or HybridCache in scenarios where caching is used at the service or repository level, or where the cached value feeds into further processing before the response is formed.

Is HybridCache's coalescing guarantee cluster-wide or per-instance? Per-instance. The stampede protection in HybridCache prevents multiple concurrent requests on the same instance from all executing the factory simultaneously. It does not prevent two different pods in a Kubernetes cluster from both executing the factory at the same time for the same key. For cluster-wide coalescing, a distributed lock (Redis SET NX or a similar primitive) is required. In practice, per-instance protection is sufficient for most workloads — the factory executes once per instance, not once per request.

Should I use AbsoluteExpiration or SlidingExpiration to reduce stampede risk? Absolute expiration with jitter is generally safer. Sliding expiration extends the TTL on every access, which means that for popular keys, the entry may never expire cleanly — but when it eventually does expire (because traffic drops overnight, for example), all clients that start hitting it in the morning will find a cold cache simultaneously. Absolute expiration with a small random jitter gives more predictable expiry distribution and makes the stampede window easier to reason about.

Does the ConcurrentDictionary used for the semaphore lock introduce its own thread safety issues? No. ConcurrentDictionary<TKey, SemaphoreSlim> is thread-safe for concurrent reads and writes. The standard pattern — GetOrAdd to retrieve or create the semaphore, WaitAsync to acquire it, Release to free it, and then removal of the entry after the factory completes — is safe under concurrent access. The entry-removal step requires care to avoid a race where a newly added entry is removed before another caller has a chance to acquire it; the typical fix is to check the cache again after acquiring the semaphore before executing the factory.

The complete patterns and trade-off comparisons covered in this article are explored inside a production-ready codebase on Patreon — with real service classes, handler implementations, and annotated examples showing exactly when each approach pays off in a working ASP.NET Core API.

Understanding how constructors fit into clean, layered code is also a core theme in Chapter 11 of the ASP.NET Core Web API: Zero to Production course — which covers Clean Architecture with CQRS and MediatR, where constructor design choices directly affect how handlers, repositories, and domain services wire together.

What Are Primary Constructors in C#?

Primary constructors let you declare constructor parameters directly on the class declaration, making them available throughout the type body without requiring explicit field declarations. They've existed for records since C# 9, but C# 12 extended them to classes and structs.

For a service class with injected dependencies, a primary constructor collapses what used to be four or five lines of boilerplate field declaration, constructor signature, and field assignment into a single line at the class declaration.

In ASP.NET Core, the most common use case is constructor injection. The DI container resolves the dependencies and passes them to the constructor — and with primary constructors, that process is identical at the container level. The difference is entirely in how you write and read the class definition.

The Core Difference: How Each Approach Wires Dependencies

With a traditional constructor, you explicitly declare private readonly fields, write a constructor that accepts parameters, and assign each parameter to its corresponding field. The result is verbose but explicit: every dependency has a visible, named, immutable home in the type.

With a primary constructor, the parameters are declared on the class line and captured implicitly. You reference them directly in the class body — no field assignment needed. The parameter name itself becomes your reference throughout the type.

The critical difference that trips up enterprise teams: primary constructor parameters are captured as mutable variables, not readonly fields. If you reassign a primary constructor parameter inside the class body, the compiler will not stop you. Traditional constructors with private readonly fields enforce immutability at compile time.

Side-by-Side Comparison

When Primary Constructors Are the Right Choice

Record types and immutable DTOs. Primary constructors were designed for records. If you are writing a result type, a request model, or a value object, primary constructors are natural and idiomatic. There is no meaningful downside here.

Simple, focused service classes. If a class has one or two dependencies, does one job, and is unlikely to grow significantly, primary constructors reduce noise without adding risk. Small query handlers, simple validators, and adapter classes are good candidates.

Test classes. When using a framework like xUnit, primary constructors on test classes clean up test fixture setup considerably. The risk of accidental reassignment is low in test contexts, and the readability gain is real.

Teams with strong Roslyn analyser coverage. If your team runs a linter or analyser that flags primary constructor parameter reassignment (such as rules from Roslynator or JetBrains Rider/ReSharper), the safety concern diminishes significantly.

When Traditional Constructors Are the Right Choice

Service classes with three or more dependencies. When a class grows, the implicit capture model of primary constructors makes it harder to see at a glance which dependencies a type holds. A traditional constructor with declared fields gives any developer an immediate inventory of what the class depends on.

Classes where immutability matters explicitly. Any service, repository, or domain object where you want the compiler to enforce that injected dependencies cannot be replaced mid-object-lifetime should use private readonly fields. This is a non-trivial safety property in long-lived singleton services.

Public or protected classes in library or SDK code. If external consumers can inherit from your class, the implicit parameter capture model can confuse inheriting developers. Traditional constructors with clearly documented parameters are the safer public API surface.

Classes with complex initialization logic. If your constructor does more than simple field assignment — configuring options, validating preconditions, or initialising derived state — a traditional constructor body is cleaner and more intentional.

Teams working across a mix of C# versions. If parts of your codebase target older runtimes or contributors use older tooling that has limited primary constructor support in editors and analysers, consistency may favour staying with traditional constructors project-wide.

The Mutable Capture Problem in Detail

The single biggest risk with primary constructors in service classes is the mutable capture semantics. In a traditional constructor, once you write _service = service, the field is readonly and cannot be overwritten. The compiler enforces this.

With a primary constructor, the parameter service is not backed by a readonly field. You can write service = null; inside any method body and the compiler will accept it silently. The DI container still injects correctly. The mutable capture only becomes a problem if someone accidentally or intentionally reassigns the parameter — but in large codebases with many contributors, silent mutability is a footgun.

Teams that adopt primary constructors for ASP.NET Core services should pair them with a Roslyn analyser rule that flags any reassignment of primary constructor parameters in non-record class bodies.

Does It Affect Performance?

No. Primary constructors and traditional constructors compile to identical IL in practice for simple injection scenarios. The JIT sees the same constructor invocation, the same field storage (even if the C# source doesn't show it explicitly), and the same method calls. There is no performance argument for either approach.

What Does Microsoft's Own Codebase Do?

Microsoft's ASP.NET Core team has adopted primary constructors selectively in .NET 9 and .NET 10 source. The pattern appears most in simple internal service implementations, test helpers, and record-like types. The more complex services in the framework — those with several dependencies and complex lifecycles — continue to use traditional constructors with explicit field declarations.

This mirrors the practical recommendation for enterprise teams: use primary constructors where they simplify the code without introducing implicit state concerns, and stick with traditional constructors where explicitness has value.

Is There a Middle Path?

Some teams adopt a hybrid convention:

• Records and simple value types: primary constructors always

• Small handler and adapter classes (≤2 dependencies): primary constructors allowed

• Service classes with ≥3 dependencies or complex lifecycle: traditional constructors required

• Abstract base classes or public library types: traditional constructors required

This approach captures most of the readability gains from primary constructors while preserving explicitness where it matters most. The key is documenting the convention and enforcing it through code review, not leaving it to individual judgment.

How to Choose: Decision Framework

Ask these questions before reaching for primary constructors in a new class:

1. Is this a record type or immutable DTO? → Primary constructor is the natural choice.

2. Does this class have more than two injected dependencies? → Traditional constructor preserves clarity.

3. Will this class be inherited or used as a public API surface? → Traditional constructor is safer.

4. Does your team have an analyser rule for primary constructor parameter reassignment? → If yes, primary constructors are safer. If no, weigh the risk.

5. Is this a test fixture or adapter class? → Primary constructor typically wins on readability.

There is no wrong answer that applies to all scenarios. The goal is intentional consistency, not a fleet-wide mandate in either direction.

Refactoring Existing Codebases

If you are considering migrating an existing ASP.NET Core codebase from traditional to primary constructors, go incrementally. Target the simplest, lowest-risk classes first — small handlers, validators, and adapters. Leave the large, stateful service classes on traditional constructors until your team has built confidence with the new pattern and your analyser coverage is solid.

Rider and Visual Studio both offer automated refactoring to convert traditional constructors to primary constructors. Running these transformations in bulk across a large codebase is risky — it is better to migrate class by class, reviewing each transformation for the mutable capture concern before merging.

For teams following the Domain Events vs Integration Events in .NET architectural pattern, domain event handlers are typically excellent candidates for primary constructors given their focused, single-dependency nature. Larger aggregates and orchestration services are better left on traditional constructors.

Internal Links

For the DI lifetime decisions that interact with constructor design, see the post on ASP.NET Core DI Lifetimes: Singleton vs Scoped vs Transient — lifetime mismatches remain the most common constructor-related runtime error in ASP.NET Core, regardless of which constructor style you use.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

Are C# primary constructors safe to use with ASP.NET Core dependency injection? Yes. The DI container resolves and passes dependencies to primary constructors exactly as it does with traditional constructors. The difference is entirely in how the C# source is written, not how the runtime wires dependencies. There is no compatibility or registration difference.

Why are primary constructor parameters mutable in C# class types? This was a deliberate language design decision to keep primary constructors general-purpose. Unlike record types, where primary constructor parameters map directly to init-only properties, class primary constructors were designed to support scenarios beyond immutable data — including cases where the parameter value needs to change during initialisation. The downside is that you lose the compiler-enforced immutability that private readonly fields provide.

Should I convert all my existing ASP.NET Core service classes to use primary constructors? No — not as a bulk operation. Evaluate each class individually. Simple, small service classes are good candidates. Large services with multiple dependencies, complex state, or inheritance chains are better left on traditional constructors. Mass conversion without an analyser to catch mutable capture issues introduces subtle risk.

Do primary constructors work with ASP.NET Core options like IOptions<T>? Yes. IOptions<T>, IOptionsSnapshot<T>, and IOptionsMonitor<T> are injected through primary constructors in exactly the same way as through traditional constructors. The registration in Program.cs is unchanged.

Can I use primary constructors in ASP.NET Core controllers? Yes. Controller classes support primary constructors in C# 12 and later. The DI container injects action-injected dependencies normally. However, controllers tend to have more dependencies than simple service classes, so the clarity trade-off often favours traditional constructors for controllers in enterprise codebases.

What is the impact of primary constructors on code coverage and debugging? Some debuggers and coverage tools have slightly less mature support for primary constructor parameters compared to traditional fields. JetBrains Rider and Visual Studio 2026 have improved this significantly, but if you rely on field-watching in complex debugging scenarios, traditional constructors with named readonly fields give a more predictable experience.

Do primary constructors affect XML documentation in ASP.NET Core libraries? Yes, in a minor way. You cannot use <param> tags on the class declaration to document primary constructor parameters in the standard way. This is a real limitation for library authors and public SDK surfaces. Traditional constructors with explicit /// <summary> and <param> documentation on the constructor itself are better for documentation-heavy codebases.

The gap between teams that implement JWT correctly and teams that implement it insecurely is rarely about intent — it is almost always about the specific defaults they accepted without questioning them. The complete authentication patterns, including token families, refresh token rotation, and secure key management, are available with working source code on Patreon — ready to drop into a real production codebase.

If you want to see these authentication concepts wired together inside a full production API — including token rotation, policy-based authorization, and hardened defaults — Chapter 7 of the ASP.NET Core Web API: Zero to Production course covers exactly that, with a complete codebase you can run immediately.

What Broken Authentication Actually Means in ASP.NET Core APIs

OWASP API2:2023 (Broken Authentication) covers a broad class of weaknesses that all share one root cause: the API cannot reliably verify that the calling party is who they claim to be. In ASP.NET Core APIs, this typically surfaces in one of five patterns:

• Weak or predictable signing keys — JWT secrets that are too short, hardcoded in source control, or shared across environments

• Disabled or incomplete token validation — accepting tokens with alg: none, skipping audience/issuer checks, or setting ClockSkew too high

• Insecure token transmission — tokens passed over HTTP, logged to disk, or stored in localStorage on the client

• Missing expiry enforcement — long-lived access tokens with no rotation strategy, or refresh tokens that never expire

• Credential stuffing exposure — login and token endpoints with no rate limiting, no account lockout, and no anomaly detection

Each of these represents a distinct attack surface, and each requires a different mitigation. A team that has fixed the key management problem but left validation parameters at their defaults is still vulnerable — just to a different exploit.

The Threat: How Broken Authentication Is Exploited

Understanding how attackers approach broken authentication makes the mitigations more intuitive.

Weak Signing Keys

A JWT secret that is fewer than 256 bits (32 bytes) for HMAC-SHA256 can be brute-forced offline once an attacker has intercepted a token. This is not theoretical — tools exist specifically for cracking JWT secrets, and they are effective against anything shorter than a strong random key. If the key is also checked into source control, the window of exposure extends indefinitely to anyone with repository access, past or present.

The fix is not complex. Use a cryptographically random key of at least 256 bits, store it in environment variables or a secrets manager (Azure Key Vault, AWS Secrets Manager), and never commit it to source control under any circumstances. The Options pattern in ASP.NET Core — IOptions<JwtSettings> — makes it straightforward to load signing keys from the configuration hierarchy at startup without hardcoding anything.

Disabled or Incomplete Token Validation

The TokenValidationParameters class in ASP.NET Core gives developers granular control over what gets validated. The problem is that several of the most important checks are not enforced by default, and teams that copy boilerplate JWT setup code often accept those defaults without reading what they mean.

The alg: none attack is the classic example. A JWT with the algorithm field set to none carries no cryptographic signature — the server should reject it outright. Modern versions of System.IdentityModel.Tokens.Jwt handle this correctly by default, but hand-rolled or legacy validation logic may not. Always validate against a known set of accepted algorithms: ValidAlgorithms = new[] { SecurityAlgorithms.HmacSha256 }.

Audience and issuer validation are equally important. Skipping ValidateAudience or ValidateIssuer means a token issued for one of your services can be replayed against any other service that trusts the same key — a lateral movement opportunity that attackers actively look for in multi-service architectures. Both should be enabled, and the values should be specific: not *, not empty, not a development placeholder left in place.

ClockSkew defaults to five minutes in ASP.NET Core. That means a token whose expiry says 14:00:00 is still accepted until 14:05:00 on any server. For most production systems, setting ClockSkew = TimeSpan.Zero is the correct posture. If you need a small tolerance for clock drift, keep it under thirty seconds and document why.

Token Transmission and Storage

A correctly signed, well-validated JWT is worthless if it travels over HTTP in plain text or ends up in a server log. Enforce HTTPS at the infrastructure level and use UseHttpsRedirection() as a fallback. For APIs, also consider rejecting requests that arrive without TLS — a middleware check on context.Request.IsHttps is a simple safeguard.

Logging middleware is a common culprit for token leakage. Structured logging libraries like Serilog, when configured with request body or header logging, will happily capture the Authorization header. Ensure that Authorization, Cookie, and any other credential-bearing headers are added to a destructuring exclusion list in your Serilog configuration.

On the client side, localStorage is accessible to any JavaScript running on the page — including injected scripts from a successful XSS attack. For web applications that consume your API, HttpOnly cookies provide a safer token storage mechanism. For mobile and server-to-server integrations, the token should live in memory only — never written to persistent storage.

Token Expiry and Rotation

Long-lived access tokens are a significant risk because any leak gives the attacker a long operational window. The standard guidance — and what production security postures converge on — is short access tokens (10–15 minutes) combined with a refresh token rotation strategy. When a refresh token is used to obtain a new access token, the old refresh token should be invalidated immediately. If a refresh token is used twice, that is a strong signal of theft, and the entire token family for that user session should be revoked.

ASP.NET Core does not include refresh token rotation out of the box. It requires a stored token table, a revocation check on every refresh request, and a token family concept to detect replay. This is where many teams shortcut and pay the price later. If you are building this for the first time, the effort is substantial but well worth it — and it is covered in full in Chapter 7 of the Zero to Production course.

Reference tokens — where the token is an opaque identifier that maps to session data stored server-side — are an alternative approach that makes revocation trivially simple. The trade-off is that every request requires a database or cache lookup. For internal services where that overhead is acceptable, reference tokens can be a more operationally controllable choice. The JWT vs Reference Tokens Enterprise Decision Guide covers this trade-off in detail.

Credential Stuffing and Brute-Force on Auth Endpoints

The /auth/login and /auth/refresh endpoints deserve the same rate limiting treatment as any other high-value endpoint. Without it, they become targets for credential stuffing — automated attacks that try large volumes of username/password combinations sourced from data breaches.

ASP.NET Core's built-in rate limiting middleware makes per-endpoint policies straightforward to apply. A fixed window policy on login — limiting to a small number of attempts per IP per minute — raises the cost of credential stuffing significantly. Combine this with a Retry-After response header on 429s and an account lockout mechanism (even a temporary soft lock) to push the cost even higher. The ASP.NET Core Rate Limiting Enterprise Policy Guide covers the implementation options in detail.

Defence-in-Depth Checklist

Is Your JWT Configuration Actually Secure?

No single control eliminates broken authentication risk. The effective mitigation is layering defences so that exploiting one weakness does not immediately compromise the system:

• ✅ Signing key: Minimum 256-bit random value, stored in secrets manager, never in source control

• ✅ Algorithm validation: Explicitly set ValidAlgorithms — reject none and any algorithm you are not actively using

• ✅ Audience and issuer: Both validated, both specific to the environment

• ✅ ClockSkew: Set to TimeSpan.Zero or under 30 seconds

• ✅ Access token expiry: 10–15 minutes maximum for user-facing APIs

• ✅ Refresh token rotation: Old token invalidated on use; token family revoked on replay detection

• ✅ HTTPS enforcement: UseHttpsRedirection() and TLS at infrastructure level; never accept credentials over HTTP

• ✅ Header logging exclusions: Authorization and Cookie headers excluded from structured log output

• ✅ Rate limiting on auth endpoints: Fixed or sliding window with Retry-After on 429 responses

• ✅ Account lockout: Temporary lockout or exponential back-off after repeated failed attempts

What Teams Get Wrong in Production

The most common failure mode is not a single wrong decision — it is a series of small shortcuts that compound. A team hardcodes the JWT secret during development and never rotates it to a secrets manager before go-live. They leave ValidateAudience = false because it was causing errors during local testing. They set a one-week access token expiry because the product team did not want users to see re-authentication prompts. They log full request headers for debugging and forget to clean that up before production.

Each of these shortcuts is understandable in isolation. Together, they create an API where a single intercepted token gives an attacker a week of access, the signing key is readable from the repo, and validation parameters are loose enough to accept forged tokens from other services. This is not a hypothetical scenario — it is the authentication posture of a significant fraction of production ASP.NET Core APIs that have not been through a formal security review.

The corrective path is methodical. Start with the signing key and token validation parameters — those fixes are low-effort and high-impact. Then address token lifetime and rotation. Then lock down the auth endpoints with rate limiting. Then audit your logging configuration for credential leakage. Treat it as a progression, not a single sprint.

When Broken Authentication Intersects with Other Risks

Broken authentication rarely operates in isolation. It interacts with several other API security risks in ways that amplify the impact:

With BOLA: If authentication is broken and an attacker obtains a valid token for any user — not just a privileged one — they can then use object-level authorization flaws to access data belonging to other users. The token provides the initial foothold; BOLA provides the lateral movement.

With Excessive Data Exposure: If token validation is loose and a service accepts tokens not intended for it, it may return responses that include more data than the legitimate caller would ever see — inadvertently exposing fields that were gated by audience/scope.

With Broken Function Level Authorization: A stolen or forged token that passes weak validation may carry claims that grant access to administrative functions the original user was never meant to reach — especially in systems where role claims are embedded in the token without server-side verification.

This is why the defence-in-depth checklist matters. Fixing authentication in isolation is necessary but not sufficient for a secure API.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

Frequently Asked Questions

What is broken authentication in the context of ASP.NET Core APIs? Broken authentication refers to weaknesses in how an ASP.NET Core API verifies the identity of callers. This includes weak JWT signing keys, incomplete token validation (skipping audience/issuer checks), insecure token transmission over HTTP, long-lived tokens without rotation, and auth endpoints exposed to brute-force or credential stuffing attacks. OWASP classifies this as API2:2023.

How short should JWT access token expiry be in ASP.NET Core? For user-facing APIs, the standard recommendation is 10–15 minutes. This limits the damage window if a token is intercepted or leaked. Short access tokens should be paired with a refresh token rotation strategy so that users are not forced to re-authenticate constantly — the refresh token silently issues a new access token before the current one expires.

What happens if I leave ValidateAudience = false in my JWT configuration? Disabling audience validation means a token issued for one service in your system can be used against any other service that trusts the same signing key. In a multi-service architecture, this creates a cross-service token replay risk — an attacker with a token for a low-privilege service can use it against a higher-privilege one, depending on what role claims are embedded.

Should I set ClockSkew to TimeSpan.Zero in production? Yes, in most cases. The default five-minute clock skew means tokens are accepted for five minutes past their stated expiry. For short-lived access tokens, this represents a 33–50% extension of the valid window. Setting ClockSkew = TimeSpan.Zero eliminates this, but requires your server clocks to be synchronised (NTP, or cloud-provider time sync — which is standard in Azure, AWS, and GCP environments).

What is refresh token rotation and why does it matter for ASP.NET Core APIs? Refresh token rotation means that when a refresh token is used to obtain a new access token, the old refresh token is immediately invalidated and a new one is issued. If the old refresh token is presented again (indicating it may have been stolen and used by an attacker), the server detects the replay and revokes the entire token family for that session. This significantly reduces the impact of refresh token theft compared to long-lived static refresh tokens.

How do I prevent JWT secrets from appearing in application logs in ASP.NET Core? Configure your structured logging provider (Serilog, for example) to exclude the Authorization and Cookie headers from request log output. This is typically done through destructuring policies or explicit header exclusions in the UseSerilogRequestLogging() configuration. Also ensure that exception handlers never log the full request body — a login request body contains plaintext credentials.

Is rate limiting on the login endpoint enough to prevent credential stuffing? Rate limiting raises the cost significantly but is not a complete defence on its own. Effective credential stuffing mitigation combines rate limiting per IP, per username (to detect distributed attacks), temporary account lockout after repeated failures, Retry-After headers on 429 responses, and ideally CAPTCHA or bot detection for web-facing login flows. Each layer makes automated attacks less economical.

If you want to go beyond the checklist and see these patterns wired into a complete production API — with policy handlers, resource-based checks, and M2M auth all working together — the full implementation is on Patreon, annotated and ready to adapt for your own system.

Authorization in isolation is understandable. Seeing how role policies, resource-level checks, and API key middleware interact inside a single production codebase is what actually makes the decisions click. Chapter 8 of the ASP.NET Core Web API: Zero to Production course covers exactly that — walking through every authorization layer inside one connected API, with source code you can run immediately.

Why Authorization Fails in Production

Most authorization failures are not caused by the absence of controls — they are caused by controls applied inconsistently. A team might use [Authorize(Roles = "Admin")] on some endpoints, named policies on others, and nothing at all on a handful of internal endpoints that were "only for testing." Over time, these inconsistencies become exploitable.

The checklist format works well for authorization because the failure mode is usually omission, not misunderstanding. Teams know what to do — they just need a reliable way to verify it is actually done everywhere.

The Checklist

✅ 1. Register a Default Fallback Policy

Every API should require authentication by default. Rather than placing [Authorize] on each controller or endpoint individually, register a fallback policy at the application level using AddAuthorizationBuilder. This means forgetting to add [Authorize] to a new endpoint does not silently open it to unauthenticated callers. Endpoints that must be public are then explicitly opted out with [AllowAnonymous].

This one control closes entire classes of accidentally public endpoints.

✅ 2. Use Named Policies — Never Inline Role Strings

Hard-coded role strings scattered across attributes ([Authorize(Roles = "Admin,Manager")]) are a maintenance and audit nightmare. Define authorization requirements as named policies in a central location — typically an AuthorizationPolicies static class or similar. Each policy gets a clear name, and the role membership or claim logic lives in one place.

When a role is renamed or a new requirement is added, the change happens once. When you want to understand what "ContentEditor" can access, you look in one file — not across forty controllers.

✅ 3. Write Custom IAuthorizationRequirement for Non-Trivial Logic

Built-in helpers like RequireRole and RequireClaim cover simple cases. Any authorization logic that needs database access, time-windowed conditions, or multi-claim evaluation belongs in a dedicated AuthorizationRequirement and AuthorizationHandler<T> pair.

This keeps authorization logic testable in isolation — you can write unit tests against the handler without spinning up the full request pipeline. It also makes the intent explicit: MinimumSubscriptionTierRequirement is far more descriptive than a chain of claims comparisons inline in a controller action.

✅ 4. Apply Resource-Based Authorization for Ownership Checks

A policy check verifies what a user is allowed to do in general. Resource-based authorization verifies what a user is allowed to do with a specific record. The two serve different purposes and both are necessary in most real applications.

Use IAuthorizationService.AuthorizeAsync(user, resource, policyName) at the handler or service layer when an action depends on who owns the resource — not just what role the caller has. An Orders endpoint might require authentication (policy) and additionally require that the authenticated user owns the specific order being modified (resource check). Skipping the resource check is how BOLA vulnerabilities appear.

✅ 5. Separate Authentication from Authorization Middleware Position

UseAuthentication() and UseAuthorization() must appear in the correct order in the middleware pipeline, and both must appear after UseRouting() but before UseEndpoints() (or MapControllers()). Swapping them, or placing them before routing, produces silent failures where the authenticated identity is never populated when authorization runs.

Review Program.cs and verify the order explicitly: exception handling → HSTS → HTTPS redirection → static files → routing → CORS → authentication → authorization → endpoint mapping.

✅ 6. Lock Down Machine-to-Machine Endpoints

Service-to-service calls should not share the same authorization path as user-facing endpoints. Implement a dedicated API key middleware or OAuth 2.0 client credentials flow for M2M scenarios. The middleware should validate the key against a stored hash (never plaintext), return 401 on missing keys, and return 403 on valid but unpermitted keys.

If API keys are used, ensure they are scoped — a key issued to a background worker should not have the same permissions as a key issued to an external partner. Store which key maps to which service identity so audit logs are meaningful.

✅ 7. Return 403 — Not 404 — When Authorization Fails on a Known Resource

A common mistake is returning 404 Not Found when an authorized user tries to access a resource they are not permitted to view — the intent being to hide whether the resource exists. While this is sometimes appropriate for high-sensitivity resources, it is often applied wholesale and incorrectly. The result is that legitimate permission errors look like "not found" in logs and during debugging, making support and incident response harder.

Use 403 Forbidden when the resource exists and the caller is authenticated but not permitted. Reserve the 404 approach for resources where existence itself is sensitive (e.g., protected files, confidential records).

✅ 8. Test Each Policy in Isolation

Every named policy and every custom AuthorizationHandler should have a corresponding unit test. Use AuthorizationHandlerContext directly in tests — you do not need a web host to test handler logic. Verify both the success and failure paths, and test boundary conditions for time-windowed or claim-value-based requirements.

Authorization tests are cheap to write and expensive to skip. A passing CI pipeline with no authorization tests gives false confidence.

✅ 9. Log Authorization Failures at the Right Level

Failed authorization attempts — both authentication failures (401) and permission denials (403) — should be logged at Warning level, not Information. Include the requesting identity (or "anonymous"), the endpoint path, and the specific policy or resource that failed. This makes security incident investigation tractable.

Avoid logging at Error for expected authorization failures. Error-level noise in auth logs drowns out genuine problems. Reserve Error for unexpected exceptions inside authorization handlers.

✅ 10. Scope Policies to the Minimum Required Permission

It is tempting to create broad policies like "CanManageEverything" for administrative users and apply them everywhere for convenience. This approach grants more permission than required for each action and makes the blast radius of a compromised admin account larger than necessary.

Define policies at the granularity of the operation — "CanPublishContent", "CanArchiveContent", "CanDeleteContent" — rather than the role. Roles then become collections of policies, not permission boundaries in themselves. This approach maps directly to RBAC best practices and makes permission audits straightforward.

✅ 11. Audit the Authorization Surface Before Each Release

Before shipping a new feature or releasing a new API version, audit the authorization surface: are all new endpoints covered by the fallback policy or an explicit [Authorize]? Are all write operations protected? Are any sensitive GET endpoints missing ownership checks? Have any [AllowAnonymous] exemptions been added without a documented reason?

This does not need to be a heavyweight process. A five-minute review of new endpoints against the checklist catches most regressions before they ship.

✅ 12. Document Who Can Do What — And Review It Quarterly

Authorization logic lives in code, but the permission model it implements is a business decision. Document the intended permission matrix for your API — which roles or policies grant access to which operations — and review it quarterly with the team. This surfaces role creep (permissions that were added temporarily and never removed) and ensures that the code-level authorization model still reflects the current business intent.

A permission matrix in a Confluence page or a README section takes an hour to write and prevents months of confusion.

What Is the Best Way to Implement Authorization in ASP.NET Core?

The best approach combines three layers: a default fallback policy that requires authentication globally, named policies for operation-level control, and resource-based authorization for ownership checks. Each layer addresses a different failure mode. Relying on any single layer leaves gaps that the others would have caught.

Authorization Anti-Patterns to Avoid

Checking roles in business logic — Authorization belongs in the authorization layer, not inside services or repositories. Business logic that checks HttpContext.User.IsInRole("Admin") is hard to test and easy to miss during refactoring.

Using [Authorize] without a policy name — A bare [Authorize] only checks that the user is authenticated. It does not verify any permission. Most write operations need more than this.

Skipping resource-based checks — Policy checks alone do not prevent users from accessing other users' data. Resource-based authorization is not optional when data ownership matters.

Sharing API keys across services — A single shared API key means a compromised key affects every service it was given to. Issue scoped keys per service and rotate them on a defined schedule.

Allowing authorization exceptions to surface as 500s — Exceptions inside AuthorizationHandler implementations should be caught and logged. An unhandled exception in an authorization handler can result in a 500 Internal Server Error that leaks stack trace information and bypasses the intended 403 response.

☕ Find the checklist useful? Buy us a coffee — it keeps the content coming!

Frequently Asked Questions

What is the difference between authentication and authorization in ASP.NET Core? Authentication answers "who are you?" — it validates identity through tokens, cookies, or certificates. Authorization answers "what are you allowed to do?" — it checks whether the authenticated identity has the required permissions. In ASP.NET Core, UseAuthentication() runs first and populates HttpContext.User; UseAuthorization() runs after and evaluates policies against that identity. Both are required, and order matters.

What is a fallback authorization policy in ASP.NET Core? A fallback authorization policy is applied to any endpoint that does not have an explicit authorization attribute — neither [Authorize] nor [AllowAnonymous]. Setting a fallback policy that requires authentication ensures that new endpoints are protected by default, so omitting an [Authorize] attribute does not silently create a public endpoint. You configure this via AddAuthorizationBuilder().SetFallbackPolicy(...) in Program.cs.

When should I use resource-based authorization instead of policy-based authorization? Use policy-based authorization when the permission depends on who the user is (their role, claims, or subscription tier). Use resource-based authorization when the permission also depends on the specific resource being accessed — for example, verifying that the authenticated user is the owner of the order they are trying to modify. Most real-world APIs need both.

How do I test authorization handlers in ASP.NET Core? Instantiate the handler directly in a unit test and call HandleAsync with a constructed AuthorizationHandlerContext. Pass a mock or stub resource if required. Assert on context.HasSucceeded or context.HasFailed. This approach tests the handler logic without needing a full HTTP request pipeline, making tests fast and focused.

What HTTP status code should a failed authorization return? Return 401 Unauthorized when the caller is not authenticated (no identity established). Return 403 Forbidden when the caller is authenticated but does not have the required permission. Using 404 to hide resource existence is sometimes appropriate for sensitive cases but should be a deliberate, documented decision — not a default behavior applied everywhere.

How should API keys be implemented for service-to-service authorization in ASP.NET Core? Implement a custom middleware that reads an X-Api-Key header, hashes the value, and compares it against stored hashed keys. Never store API keys in plaintext. Associate each key with a service identity so authorization handlers can treat the service as a principal with defined permissions. Return 401 if the key is missing and 403 if the key is valid but the associated service lacks the required permission.

What is the recommended way to handle authorization failures without leaking information? Return 403 Forbidden with a Problem Details response body. The body should describe the error type (AuthorizationFailure) and a generic message (Insufficient permissions) — never include the specific policy name, resource ID, or claim values in the response. Log the full detail server-side at Warning level for audit purposes.

The full working examples, production-ready Serilog configuration, and log enrichment patterns are available on Patreon — with annotated source code you can drop straight into an existing ASP.NET Core project.

Understanding Chapter 14 of the ASP.NET Core Web API: Zero to Production course is where this clicks into place — it covers structured logging with Serilog, UseSerilogRequestLogging, log levels, and OpenTelemetry in the same chapter, wired into a full production codebase.

Mistake 1: Using String Interpolation Instead of Message Templates

This is the most widespread logging mistake in .NET codebases, and it costs you more than you might expect.

When you write _logger.LogInformation($"User {userId} logged in"), you get a formatted string. The log provider stores it as plain text. You lose the ability to query by userId later, and you pay the cost of string allocation even when the log level is filtered out.

The correct approach is to use named placeholders in the message template:

_logger.LogInformation("User {UserId} logged in", userId);

With named placeholders, structured log providers like Serilog capture UserId as a first-class searchable property. You can then run queries like WHERE UserId = '123' in Seq, Loki, or Application Insights without parsing free-form text. This matters enormously at scale — filtering by message text is slow, filtering by a structured property is fast.

The performance gain is also real. ILogger checks whether the log level is enabled before formatting the message. With string interpolation, the interpolation happens before the check. With message templates, nothing is allocated if the log level is filtered.

The fix: Replace every interpolated log string with a structured template. If you are working on a large codebase, use a Roslyn analyser (the Microsoft.Extensions.Logging.Analyzers NuGet package includes CA2254) to catch violations automatically.

Mistake 2: Logging at the Wrong Level

Every team has a production system where warnings dominate and errors are drowned out, or a system where everything is Information and the noise-to-signal ratio is impossible. Wrong log levels are a silent problem — they don't break anything, but they make your logs unreliable as a diagnostic tool.

The practical rule for ASP.NET Core APIs:

• Trace / Debug: Development only. Entering a method, loop iterations, variable states. Should never reach production log sinks.

• Information: Something meaningful happened. A request completed, a scheduled job ran, a user authenticated. Readable in production but filtered in high-traffic environments.

• Warning: Something unexpected but recoverable. A retry succeeded, a fallback was triggered, a deprecated path was hit.

• Error: Something failed that should not have. An operation that was expected to succeed did not. Requires investigation.

• Critical: The application is about to stop or has entered an unrecoverable state.

The most common violation is logging caught exceptions at Information. If you caught an exception and decided to continue, it belongs at Warning at minimum — you expected the happy path, something went wrong, but you recovered. Log the exception object, not just the message:

_logger.LogWarning(ex, "Downstream service unavailable, using cached result for {CustomerId}", customerId);

Passing the exception as the first argument ensures the full stack trace is captured by structured providers. Many developers mistakenly log only ex.Message, which throws away the stack trace entirely.

The fix: Audit your log calls by level. Every LogError should represent a genuine failure requiring investigation. Every LogWarning should represent something abnormal but handled. LogInformation should be readable and meaningful, not a wall of method-entry noise.

Mistake 3: Not Filtering Log Levels Per Namespace in appsettings.json

The default appsettings.json logging configuration looks innocuous:

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Warning"
  }
}

But many teams stop here and never tune it further. The result is that EF Core logs every SQL query at Information in production, ASP.NET Core internal pipeline logs clutter your sinks, and Microsoft framework noise makes real application events hard to find.

The fix is to apply category-level filters. EF Core's SQL logging, for example, belongs at Debug in production:

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Warning",
    "Microsoft.EntityFrameworkCore.Database.Command": "Warning",
    "System.Net.Http.HttpClient": "Warning"
  }
}

Setting Microsoft.EntityFrameworkCore.Database.Command to Warning suppresses the SQL query logs unless they fail. Setting System.Net.Http.HttpClient to Warning suppresses the lifecycle noise from IHttpClientFactory-managed clients.

Also remember that appsettings.Development.json should override these to Debug or Trace for local development, giving you full visibility without polluting production sinks.

The fix: Treat appsettings.json log configuration as a first-class concern. Profile your production log output and suppress framework namespaces that produce noise without diagnostic value.

Mistake 4: Logging Sensitive Data

Developers log user input and request data to make debugging easier — and accidentally build a PII audit trail that violates GDPR, HIPAA, or their own data handling policy. Passwords, tokens, credit card numbers, email addresses, and user identifiers in log sinks are a compliance incident waiting to happen.

The most common vector is logging the entire request body or a model that contains sensitive fields. This often happens during debugging and gets committed without review.

For Serilog users, the Serilog.Expressions destructuring policies let you strip sensitive properties from logged objects before they reach any sink. You can also use [LogMasked] from Destructurama.Attributed to annotate DTO properties that should be redacted:

public class LoginRequest
{
    public string Username { get; set; }

    [NotLogged]
    public string Password { get; set; }
}

For teams using the built-in ILogger, the pattern is to avoid logging model objects directly — log only the properties you specifically need, by name.

The fix: Establish a team rule: never log objects that might contain credentials, payment data, or user-identifying information without explicit scrubbing. Add a code review checklist item for any log call that destructures (@) an object. For Serilog-based teams, configure destructuring policies at setup time rather than relying on per-developer discipline.

Mistake 5: Injecting ILogger Statically or via LoggerFactory.Create

Some codebases — often older ones migrated to ASP.NET Core from .NET Framework — use LoggerFactory.Create or static logger instances instead of constructor injection. This bypasses the DI-managed provider chain, which means:

• Configuration changes in appsettings.json have no effect

• The logger does not inherit sink configuration from the host

• Log enrichers (like request correlation IDs or environment names) are not applied

• The logger cannot be replaced in tests

The correct approach is always to inject ILogger<T> through the constructor:

public class OrderService
{
    private readonly ILogger<OrderService> _logger;

    public OrderService(ILogger<OrderService> logger)
    {
        _logger = logger;
    }
}

The generic type parameter <T> is the log category name. It corresponds to the class the logger belongs to, which is what you use in appsettings.json to configure per-namespace filtering (see Mistake 3).

The fix: Grep for LoggerFactory.Create, new Logger, or direct Serilog.Log. calls outside of Program.cs. Any logger instantiated outside the DI container is a liability. The only legitimate place for static logger access is early in Program.cs before the host is built — for bootstrap logging only.

Mistake 6: Missing Correlation IDs Across Service Boundaries

In a distributed system — or even a monolith with multiple background jobs — the same root request spawns multiple log entries. Without a shared correlation ID, you cannot trace a single user request through its entire lifecycle. You end up with a sea of disconnected log entries and no way to reconstruct what happened.

ASP.NET Core provides IHttpContextAccessor to read the HTTP context, and the X-Correlation-ID header convention is widely adopted. The right place to handle this is in middleware: read or generate a correlation ID on each incoming request, add it to the current activity, and enrich all log entries for that request automatically.

With Serilog, UseSerilogRequestLogging() captures request-level metadata (duration, status code, path) in a single structured log event per request — which is far more useful than the separate per-request entries that ASP.NET Core emits by default. Pair it with a middleware that calls LogContext.PushProperty("CorrelationId", correlationId) and every log entry in that request automatically carries the correlation ID.

For how to choose the right log aggregation platform to query correlation IDs across services, the Seq vs Grafana Loki vs Azure Application Insights comparison breaks down which tool fits which team size and budget.

The fix: Add correlation ID middleware early in your pipeline. Enrich every log entry with the correlation ID via Serilog's LogContext or a custom ILogger scope. Make it a deployment standard, not an optional enhancement.

Mistake 7: Logging Too Much or Too Little in the Application Layer

Teams swing between two failure modes: logging every method entry and exit (producing gigabytes of noise), or logging only at the controller layer and missing everything that happens inside services and repositories.

The right model is to log at decision points, not execution points:

• Log when a significant decision is made — a feature flag resolved to an alternate path, a payment was approved, a rate limit was triggered

• Log when something unexpected happened but was handled — a cache miss forced a database fallback, a downstream service returned a non-2xx response

• Do not log routine reads, validation passes, or anything that happens on every request unconditionally

Background services are a particular trap. A hosted service that polls every second and logs "Background job started" and "Background job completed" on each cycle generates 172,800 log entries per day from a single host. None of them are useful unless something actually went wrong.

The EF Core SaveChanges path is another. Logging every database write at Information level in a write-heavy API produces noise proportional to your traffic — not to the number of things worth knowing about.

The fix: Review your application layer logs as a product decision. For every recurring log entry, ask: "When would I actually look at this?" If the honest answer is "only when something is broken" — that's Debug or Trace, not Information. Reserve Information for log entries that tell a meaningful story about what the system is doing.

Bring It Together

These seven mistakes share a common root cause: treating logging as an afterthought rather than an architectural concern. Logging that is noisy enough to ignore is just as harmful as no logging at all — in both cases, you are flying blind when production issues occur.

The fixes are straightforward once identified: use message templates, choose log levels deliberately, filter by namespace, protect sensitive data, use DI-managed loggers, add correlation IDs, and log decisions not executions.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What is the most common ASP.NET Core logging mistake? Using string interpolation ($"...") instead of structured message templates. Interpolation produces plain text that cannot be queried by property, and it allocates a string even when the log level is filtered out. Use named placeholders like "User {UserId} logged in" instead.

Should I use Serilog or the built-in ILogger in ASP.NET Core? Use ILogger<T> from Microsoft.Extensions.Logging throughout your application code regardless of your chosen provider. Serilog, NLog, and other providers plug in as sinks behind that abstraction. Your application code should never reference Serilog.Log directly — that's provider configuration, not application logic.

What log level should I use for exceptions in ASP.NET Core? Caught exceptions that were handled and from which the application recovered should be logged at Warning. Exceptions that represent genuine failures requiring investigation should be Error. Always pass the exception object as the first argument (before the message template) so structured providers capture the full stack trace.

How do I prevent sensitive data from appearing in logs? Avoid logging objects or models that may contain sensitive fields. For Serilog, configure destructuring policies or use [NotLogged] from Destructurama.Attributed on DTO properties. For built-in ILogger, log only the specific properties you need by name — never log a raw request body or an authentication model.

What is UseSerilogRequestLogging and why should I use it?UseSerilogRequestLogging() is Serilog's ASP.NET Core integration method that replaces the multiple per-request log entries ASP.NET Core emits by default with a single structured log event per request, including duration, status code, and path as structured properties. It reduces noise significantly in high-traffic APIs and makes per-request analysis far easier in log aggregation tools.

How do I add correlation IDs to all log entries in ASP.NET Core? Create a middleware that reads the X-Correlation-ID header (or generates a new GUID if absent), then calls Serilog.Context.LogContext.PushProperty("CorrelationId", correlationId) inside a using block for the lifetime of that request. Every log entry written during that request automatically inherits the correlation ID as a structured property.

Why are my log level filters in appsettings.json not working? Log level configuration is applied hierarchically by namespace. If you set "Default": "Information", all categories inherit that unless overridden. For EF Core SQL logs, explicitly set "Microsoft.EntityFrameworkCore.Database.Command": "Warning". Also verify that your Serilog or NLog setup reads from the Logging section of configuration — some setup guides configure the provider directly in code, which bypasses appsettings.json filters entirely.

The distinction becomes especially important in ASP.NET Core projects built around Clean Architecture or CQRS, where the boundaries between your domain layer, application layer, and external infrastructure must stay sharp. For teams building these patterns in a real production codebase, Chapter 11 and 12 of the ASP.NET Core Web API: Zero to Production course cover exactly this — Clean Architecture, CQRS with MediatR, the Outbox pattern, and domain events all wired together in a full codebase you can run immediately.

Understanding where your domain ends and your infrastructure begins is what makes the difference between a maintainable codebase and one that bleeds responsibilities across every layer. The patterns covered in this article go much deeper on Patreon, with production-ready source code that shows how domain events dispatch through MediatR pipeline behaviors, how integration events publish via the Outbox, and how the two co-exist cleanly without coupling.

What Are Domain Events?

A domain event represents something that happened within your bounded context — a fact about your domain model. It is raised inside the domain layer, dispatched in-process, and consumed by handlers within the same application boundary. It does not cross a network, does not involve a message broker, and is not durable by default.

The typical shape: an order is placed, an OrderPlaced domain event fires, and handlers within the same process react — perhaps applying a discount policy, checking inventory, or publishing an audit entry. All of this happens synchronously in the same transaction window, or asynchronously via an in-memory dispatcher like MediatR.

Domain events are synchronous in intent even when dispatched asynchronously. Their purpose is to keep your domain model free of direct dependencies on side-effect logic. Instead of your Order entity calling an email service or a notification handler, it raises OrderPlaced and lets the application layer wire the consequences together through handlers.

Key characteristics:

• Scope: In-process, same bounded context
• Dispatcher: MediatR INotification + INotificationHandler<T>, or a simple IDomainEventDispatcher
• Durability: Not durable — if the process crashes after raising the event but before handling, the event is lost
• Coupling: Handlers are registered via DI — no shared infrastructure required
• Transaction: Can participate in the same database transaction as the originating aggregate change

What Are Integration Events?

An integration event is a message published across a process boundary — to another service, another bounded context, or any external consumer. It represents a contract between systems, not an internal domain concern.

Where a domain event is a private signal within your model, an integration event is a public broadcast. It travels over a message broker (RabbitMQ, Azure Service Bus, Kafka), persists durably, and must be designed with versioning, idempotency, and consumer compatibility in mind from the start.

The typical shape: after an order is confirmed, the Order service publishes an OrderConfirmed integration event. The Notification service, the Inventory service, and the Analytics service each subscribe independently. They receive the event even if the Order service is briefly offline, because the broker persists it.

Key characteristics:

• Scope: Cross-process, cross-service, across bounded contexts
• Transport: Message broker — RabbitMQ, Azure Service Bus, Kafka, MassTransit, NServiceBus
• Durability: Durable — the broker guarantees delivery even across transient failures
• Coupling: Consumers depend only on the message contract, not the publishing service's implementation
• Transaction: Must be handled with the Outbox pattern to guarantee atomic publishing alongside the database write

How Do Domain Events and Integration Events Relate?

The most reliable pattern in production ASP.NET Core systems is: domain events trigger the creation of integration events via the Outbox pattern.

Here's the flow:

1. An aggregate raises a domain event (OrderPlaced) during the command handler
2. A domain event handler subscribes to OrderPlaced and writes an OrderConfirmedIntegrationEvent record to the Outbox table — as part of the same SaveChanges call
3. A background processor reads the Outbox, publishes the integration event to the message broker, and marks the record as processed

This pattern solves the dual-write problem: you can't atomically write to a database and publish to a broker in a single transaction. The Outbox bridges that gap. Your ASP.NET Core Outbox Pattern guide covers the full implementation pattern in detail.

Domain events and integration events do not compete — they compose. Domain events are the internal mechanism for reacting to changes within your model. Integration events are the external mechanism for communicating those changes to the outside world.

Side-by-Side Comparison

When to Use Domain Events

Use domain events when:

• You need to react to a state change within your domain model without coupling the aggregate to side-effect logic
• The reaction happens in the same process and participates in the same unit of work
• You want to enforce the dependency rule: domain layer raises events, application layer handles them
• The consequence is immediate and does not need to cross a service boundary

Do not use domain events for: cross-service communication, events that must survive process restarts, or anything that requires a guaranteed delivery contract with external consumers.

When to Use Integration Events

Use integration events when:

• A state change in one service must notify another service
• The consuming service is deployed independently and has its own database
• You need guaranteed delivery — the broker must hold the event until the consumer acknowledges it
• The event represents a public contract that other teams or services depend on

Do not use integration events for: internal reactions within the same bounded context. Routing everything through a message broker for in-process concerns adds latency, infrastructure complexity, and debuggability overhead for zero gain.

Is It Always Domain → Integration Events?

Not necessarily. Some teams use integration events without domain events — a command handler writes to the Outbox directly, skipping the domain event layer entirely. This is simpler, and for workflows without a rich domain model, it is often the right call.

Other teams use domain events without integration events — a single-service application where all reactions are in-process and no cross-service communication is needed.

The domain-event-to-integration-event pipeline makes the most sense in systems that: have a genuine domain model with aggregates, use CQRS and Clean Architecture, and communicate with multiple other services. For CRUD APIs or simple services, adding both layers is over-engineering.

What Do Most .NET Teams Get Wrong?

Using integration events in-process. Publishing to a broker for reactions within the same service wastes infrastructure and makes debugging harder. In-process reactions belong to domain events.

Using domain events for cross-service communication. An in-memory event that raises across a service boundary doesn't cross that boundary — it just doesn't execute. Domain events cannot substitute for a message broker.

Skipping the Outbox. Publishing an integration event directly inside a transaction handler (before SaveChanges) creates a dual-write problem. If the broker publish succeeds but SaveChanges fails, the event was never supposed to fire. Always write to the Outbox table inside the same transaction, then publish from a background processor.

Treating integration event schemas as internal. Integration events are contracts. Renaming a property, removing a field, or changing a type without versioning breaks all consumers silently. Apply the same discipline as a REST API: additive changes only, version for breaking changes.

For teams working through the CQRS and MediatR implementation in ASP.NET Core, the point at which domain events should convert to integration events is one of the most frequently misunderstood decisions in Clean Architecture.

Recommendation

For a standard ASP.NET Core API that communicates with at least one other service:

• Use domain events (via MediatR INotification) for in-process reactions to aggregate state changes
• Use the Outbox pattern to bridge from domain events to integration events safely
• Use integration events over a message broker for any cross-service communication
• Keep the two layers completely separate — integration events should not re-use domain event types

For a single-service application or a simple CRUD API: skip domain events unless you have a genuine domain model. A command handler that writes directly to the Outbox and publishes via a broker is simpler and easier to trace.

☕ Building this right takes time. If this walkthrough saved you some, buy us a coffee — every bit helps keep the content coming!

FAQ

What is the difference between a domain event and an integration event in .NET? A domain event is an in-process signal within a bounded context — dispatched via MediatR or a custom dispatcher, not durable, and handled within the same transaction. An integration event is a cross-service message published to a broker (RabbitMQ, Azure Service Bus) — durable, versioned, and consumed by independent services.

Can I use MediatR for integration events in ASP.NET Core? MediatR is in-process only and is not suitable for integration events. It has no built-in broker, no persistence, and no delivery guarantee. Use it for domain events. For integration events, use a message broker with a transport library like MassTransit, NServiceBus, or direct SDK clients for Azure Service Bus or RabbitMQ.

Do I always need both domain events and integration events? No. Use domain events when you have a rich domain model with aggregates and need to keep side-effect logic out of the domain layer. Use integration events when you need to communicate with other services. A simple CRUD API may need neither. A complex microservices system will need both.

How do I prevent losing integration events if my service crashes after committing the database but before publishing to the broker? Use the Outbox pattern: write the integration event to a database table inside the same transaction as your domain change. A background processor polls the Outbox and publishes events to the broker, marking each as processed after acknowledgement. This guarantees at-least-once delivery without dual-write risk.

What is the best way to dispatch domain events in ASP.NET Core? Register domain events as INotification in MediatR and dispatch them from within your command handlers after SaveChangesAsync. You can also dispatch them inside EF Core's SaveChanges override by reading pending events from aggregates before committing. The second approach is cleaner for rich domain models — it ensures events are always dispatched atomically with the persistence operation.

Should integration events use the same types as domain events? No. They serve different purposes and evolve at different rates. Domain event types are internal — they can change freely without affecting consumers. Integration event types are public contracts — changing them requires versioning and backward-compatibility planning. Keep them in separate namespaces and assemblies, with integration events in a shared contracts project if multiple services consume them.

How do I handle failed integration event consumers in ASP.NET Core? Design consumers to be idempotent — processing the same event twice should produce the same outcome. Brokers deliver at-least-once by default. For failures, configure dead-letter queues (DLQ) on the broker so failed messages are captured for inspection rather than dropped. Retry policies with exponential backoff, combined with a DLQ, cover most production failure scenarios.

Understanding the right scope for IHttpContextAccessor is also central to building APIs that hold up under Clean Architecture constraints. Chapter 11 of the Zero to Production course covers this directly — showing how to keep the domain layer free of infrastructure concerns while still threading user context through the full request pipeline correctly.

This guide lays out the decision clearly: when IHttpContextAccessor is the right tool, when it becomes a liability, what the enterprise-approved alternative looks like, and which anti-patterns to avoid before they end up in production.

What Is IHttpContextAccessor and Why Does It Exist?

ASP.NET Core's request pipeline is built around HttpContext — the object that carries everything about the current HTTP request: headers, route values, query parameters, the authenticated user's claims, response state, and more. Inside a controller action or a middleware component, HttpContext is always available directly. The problem is everywhere else.

Services that are injected into controllers don't get HttpContext passed to them automatically. If a service registered in the DI container needs to read the current user's ID, check a request header, or inspect a claim, it has no direct path to that data. IHttpContextAccessor was introduced specifically to bridge this gap — it provides a way to reach the ambient HttpContext from any class that can participate in DI.

It works by using AsyncLocal<T> internally to store the current HttpContext and make it retrievable anywhere in the callstack during an active HTTP request. Register AddHttpContextAccessor() in your service registration, inject IHttpContextAccessor where you need it, and call .HttpContext to get the current request's context.

Simple enough. The problem is not what it does — it is where teams use it.

When IHttpContextAccessor Is the Right Choice

There are legitimate cases where injecting IHttpContextAccessor is completely appropriate.

Middleware components that need to inspect or modify the request or response are the canonical use case. Middleware sits at the HTTP layer by design, and accessing HttpContext there is expected. The accessor adds nothing over the directly available context in this case — but it is not harmful either.

Infrastructure services that are explicitly scoped to the HTTP request and live in the Infrastructure layer — such as an audit logging service that records the requester's IP address, or a request correlation service that reads the X-Correlation-ID header — are reasonable candidates for IHttpContextAccessor. These services have an intentional dependency on HTTP infrastructure, and that dependency is honest.

Scaffolded or framework-generated code often uses IHttpContextAccessor directly for simple read operations. If you are working in a small application where layering is not a concern, using it directly in a service class is pragmatic and not worth fighting.

The key indicator that IHttpContextAccessor belongs where you are putting it: the class you are injecting it into is explicitly part of the HTTP infrastructure layer and has no expectation of running outside a web request context.

When IHttpContextAccessor Becomes a Problem

The anti-pattern is injecting IHttpContextAccessor into application services, domain logic, and repositories — layers that should have no dependency on HTTP infrastructure. This creates several compounding problems.

HttpContext can be null. IHttpContextAccessor.HttpContext returns null when accessed outside an active HTTP request. This means any service that injects it is fundamentally unsafe in background jobs, hosted services, unit tests, and integration tests that do not spin up a full HTTP pipeline. Developers routinely encounter NullReferenceException in these scenarios and then add null-checks that mask the underlying architectural mistake.

It violates Clean Architecture dependency rules. In a properly layered system, the Application layer and Domain layer have no knowledge of HTTP. They receive data through method parameters, not through ambient context. Injecting IHttpContextAccessor into an application service couples the entire application layer to ASP.NET Core's HTTP infrastructure — making it impossible to use that layer in a console application, a background worker, or a test without a full web host.

It makes unit testing painful. To test a service that injects IHttpContextAccessor, you either need to mock the accessor and fabricate an HttpContext — which requires instantiating a DefaultHttpContext, populating its User with a ClaimsPrincipal, and wiring it into the mock — or you need to skip those tests entirely. Neither outcome is acceptable for services that contain real business logic.

It couples services to the HTTP request lifecycle. A service that depends on IHttpContextAccessor implicitly assumes it is only ever called during an active HTTP request. If a future requirement introduces a background process that calls the same service, the accessor returns null and the service breaks. The caller cannot know this from the service's interface.

IHttpContextAccessor was explicitly marked as unsafe by the ASP.NET Core team in specific scenarios. The GitHub issue dotnet/aspnetcore#14975 documents cases where HttpContext can return the wrong context or an already-disposed one under certain async execution patterns. The accessor is not a reliable ambient source of truth.

The Enterprise Alternative: ICurrentUser

The pattern that resolves all of these issues is a thin, domain-owned interface that abstracts the concept of "the current caller" away from its HTTP origins. Teams implement this in slightly different ways, but the shape is consistent across enterprise codebases.

The interface belongs in the Application or Domain layer and contains only what that layer actually needs:

public interface ICurrentUser
{
    string UserId { get; }
    string? Email { get; }
    IReadOnlyList<string> Roles { get; }
    bool IsAuthenticated { get; }
}

The implementation lives in the Infrastructure layer and is the only place IHttpContextAccessor appears:

public class HttpCurrentUser : ICurrentUser
{
    private readonly IHttpContextAccessor _accessor;

    public HttpCurrentUser(IHttpContextAccessor accessor)
        => _accessor = accessor;

    public string UserId =>
        _accessor.HttpContext?.User.FindFirstValue(ClaimTypes.NameIdentifier)
        ?? throw new UnauthorizedAccessException("No active user context.");

    public string? Email =>
        _accessor.HttpContext?.User.FindFirstValue(ClaimTypes.Email);

    public IReadOnlyList<string> Roles =>
        _accessor.HttpContext?.User.Claims
            .Where(c => c.Type == ClaimTypes.Role)
            .Select(c => c.Value)
            .ToList() ?? [];

    public bool IsAuthenticated =>
        _accessor.HttpContext?.User.Identity?.IsAuthenticated ?? false;
}

Registration is straightforward:

builder.Services.AddHttpContextAccessor();
builder.Services.AddScoped<ICurrentUser, HttpCurrentUser>();

With this pattern in place, application services depend only on ICurrentUser — an interface they own, with no knowledge of HTTP. Unit tests replace it with a simple in-memory stub. Background jobs can implement a different ICurrentUser that reads from a job context or returns a system identity. The HTTP infrastructure never leaks past the Infrastructure layer.

Trade-Offs and When to Keep It Direct

The ICurrentUser pattern adds indirection. For small applications without layering concerns, that indirection is pure overhead — an extra interface, an extra class, and an extra registration for something that IHttpContextAccessor could handle in a single line.

The decision matrix is straightforward:

The rule of thumb: if the class you are writing could in principle run without an HTTP request, it should not depend on IHttpContextAccessor.

Anti-Patterns to Avoid

Injecting IHttpContextAccessor into a repository. Repositories belong to the Infrastructure layer and deal with data persistence. A repository that reads the current user from the accessor is hiding an implicit dependency that should be explicit — either passed as a method parameter or resolved through a dedicated abstraction.

Using IHttpContextAccessor in a singleton service. Singletons live for the lifetime of the application. IHttpContextAccessor.HttpContext holds the current request's context, which changes on every request. Accessing it from a singleton means the singleton sees the context of whatever request happens to be executing at that moment — or null, if no request is active. This is a data race waiting to happen.

Null-checking HttpContext and silently falling back. If a service checks whether HttpContext is null and returns a default value when it is, the service is lying about its contract. Callers that rely on the user's identity for authorization decisions will silently receive incorrect data. Fail loudly — throw an exception or use a typed null object that makes the absence of a user context explicit.

Accessing HttpContext.Items for cross-layer communication. HttpContext.Items is a request-scoped dictionary that developers sometimes use to pass data between layers. This is ambient coupling — invisible to the compiler, invisible to tests, and invisible to anyone who reads the service's interface. Use DI, method parameters, or typed context objects instead.

Clean Architecture Placement Guide

For teams building Clean Architecture systems — especially those using CQRS with MediatR (see the CQRS and MediatR in ASP.NET Core: Enterprise Decision Guide) — the placement is clear:

• Domain layer: No user context injected at all. If a domain operation needs the current user's ID, it receives it as a method parameter or embedded in the command/query object.
• Application layer: Depends on ICurrentUser (owned by the Application layer). Handlers read ICurrentUser to build audit trails, enforce ownership rules, or attach author IDs to entities.
• Infrastructure layer: Contains HttpCurrentUser : ICurrentUser, which is the only class allowed to depend on IHttpContextAccessor.
• API layer: Does not inject ICurrentUser directly — it populates commands and queries with the values it needs, rather than passing the accessor downstream.

This separation means every layer is independently testable and independently deployable. If you also want to understand how authorization policies interact with this pattern, the Background Services in .NET 10 guide shows how to thread user context into background processing safely.

Microsoft's Official Position

The official ASP.NET Core documentation explicitly recommends against using IHttpContextAccessor in middleware and instead recommends passing HttpContext as a method parameter. For services outside middleware, Microsoft's guidance is to inject IHttpContextAccessor but acknowledges the risks. The GitHub issue tracking the accessor's unreliability in async scenarios is linked from the docs and has never been fully resolved — the accessor is marked as unreliable in certain async patterns by the framework team itself.

The practical enterprise interpretation: use it in Infrastructure, hide it behind an abstraction everywhere else, and never let it cross into Application or Domain.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What does IHttpContextAccessor do in ASP.NET Core?

IHttpContextAccessor provides access to the current HttpContext from any class that participates in ASP.NET Core's dependency injection system. It uses AsyncLocal<T> internally to track the active request context. Register it with AddHttpContextAccessor() and inject it where needed to read request data, user claims, headers, or response state from outside a controller or middleware.

Is it safe to inject IHttpContextAccessor into a service layer?

Not without understanding the risks. IHttpContextAccessor.HttpContext returns null when accessed outside an active HTTP request — such as in background jobs, hosted services, or unit tests. Injecting it into the service layer also couples your application logic to ASP.NET Core's HTTP infrastructure, which violates Clean Architecture principles and makes testing harder. The enterprise-recommended approach is to wrap it in an ICurrentUser abstraction and inject that instead.

Can IHttpContextAccessor return null in production?

Yes. IHttpContextAccessor.HttpContext returns null if called outside the scope of an HTTP request. This can happen in background services, IHostedService implementations, message consumers, and any code path that is not driven by an incoming HTTP request. Accessing it from a singleton service is especially risky — the singleton may hold a reference to a disposed HttpContext from a completed request.

What is the ICurrentUser pattern in ASP.NET Core?

ICurrentUser is an application-owned interface that abstracts the concept of the caller's identity away from its HTTP origins. It is defined in the Application or Domain layer and exposes only what that layer needs — typically UserId, Email, Roles, and IsAuthenticated. The implementation lives in the Infrastructure layer and reads from IHttpContextAccessor internally. Application services depend on ICurrentUser, not on IHttpContextAccessor, keeping the dependency direction clean and the code testable.

How do I test a service that needs the current user in ASP.NET Core?

If the service depends on ICurrentUser rather than IHttpContextAccessor, testing is straightforward. Create a stub implementation of ICurrentUser that returns hardcoded test values, and register it in the test DI container. No mock HTTP context required. If the service injects IHttpContextAccessor directly, you must construct a DefaultHttpContext, populate its User property with a ClaimsPrincipal, and set it on a mocked accessor — significantly more friction for the same outcome.

Should IHttpContextAccessor be registered as singleton or scoped?

IHttpContextAccessor is registered as a singleton by AddHttpContextAccessor(). The singleton registration is safe because the accessor does not store the HttpContext itself — it reads it from AsyncLocal<T>, which is request-scoped by nature. The singleton accessor reads the current request's context on every call. The risk of registering a consuming service as singleton is different: if your service is a singleton and stores a reference to a value from HttpContext, that reference may outlive the request it came from.

When should I NOT use ICurrentUser and pass the user ID as a method parameter instead?

In domain logic and entities, neither ICurrentUser nor IHttpContextAccessor should be injected. Domain objects should receive everything they need through constructor arguments or method parameters — making dependencies visible and the domain logic portable. If a domain method needs the current user's ID to enforce an ownership rule, pass it as a parameter from the application service layer. The application service reads from ICurrentUser and passes the value down; the domain object has no knowledge of where it came from.

For teams building enterprise ASP.NET Core APIs, EF Core interceptors deserve a clear-eyed answer to a simple question: when should you reach for them, and when should you not? If you want to work through these patterns inside a real production codebase — with audit fields, soft deletes, and everything wired together — the complete implementation is available on Patreon, where full source code maps directly to what production teams actually ship.

Understanding interceptors in isolation is useful — seeing them work inside a complete production API, alongside repository patterns, global query filters, and change tracking, is what makes them click. That's exactly what Chapter 3 of the ASP.NET Core Web API: Zero to Production course covers: EF Core beyond the basics, inside a full production codebase you can run immediately.

What EF Core Interceptors Actually Are

Interceptors are hooks that let you observe — and optionally modify or suppress — EF Core operations before, during, or after they execute. They operate inside EF Core's internal pipeline, which means they fire reliably on every operation that goes through your DbContext, regardless of where in your application the operation was initiated.

The official EF Core interceptors documentation covers all available interfaces in detail. In practice, the core interfaces break down by concern:

• ISaveChangesInterceptor — fires before and after SaveChanges / SaveChangesAsync; gives you access to the full ChangeTracker state
• IDbCommandInterceptor — fires at the ADO.NET command level; lets you inspect, modify, or replace the SQL being sent to the database
• IDbConnectionInterceptor — fires on connection open/close events
• IDbTransactionInterceptor — fires on transaction begin/commit/rollback
• IMaterializationInterceptor — fires when EF Core materializes query results into entity instances

For most enterprise use cases, ISaveChangesInterceptor and IDbCommandInterceptor are the two you'll actually use. The others are more specialised and rarely needed outside infrastructure-heavy scenarios.

When to Use EF Core Interceptors

Audit Logging Without Polluting Your Domain

The most compelling use case for enterprise teams is automated audit trails. When your DbContext calls SaveChanges, the ChangeTracker holds a snapshot of every entity that's being added, modified, or deleted — including what changed and what the previous values were.

An ISaveChangesInterceptor implementation can capture this state reliably and write audit records as part of the same database round-trip. The important distinction is that this happens inside EF Core's pipeline, not as a separate application-layer concern that developers have to remember to call. You register it once and it runs on every save — regardless of which service, handler, or background job triggered the change.

This is the pattern that keeps audit logic out of your domain services, your CQRS handlers, and your repository implementations. It also means new developers on the team cannot accidentally bypass auditing by forgetting to call an audit method — because there is no audit method to call. See EF Core Global Query Filters in ASP.NET Core for a complementary pattern that works well alongside interceptor-based audit trails.

Soft Delete Enforcement

Teams using soft deletes (a DeletedAt timestamp or IsDeleted flag instead of a physical DELETE) often struggle with consistency. If you enforce soft deletes in service methods or repository implementations, the enforcement is brittle — it depends on every call site doing the right thing.

An ISaveChangesInterceptor can intercept EntityState.Deleted transitions and convert them to EntityState.Modified with the DeletedAt field set, before EF Core generates SQL. The entity never reaches the database as a delete statement. This approach pairs naturally with EF Core Global Query Filters, which filter soft-deleted records out of all queries automatically.

Query Hints and Read Replica Routing

IDbCommandInterceptor fires at the ADO.NET command level, which means you can inspect the SQL text before it executes and append or modify it. This is where teams implement things like:

• Appending NOLOCK or WITH (NOLOCK) hints to read queries in SQL Server environments where dirty reads are acceptable
• Routing read-only queries to a read replica connection string by replacing the connection on specific command types

This is admittedly an advanced use case and comes with sharp edges — particularly for NOLOCK which trades consistency for speed. But when the team has made a deliberate decision to use these patterns, interceptors are the cleanest place to centralise that logic rather than spreading it across every raw SQL call.

Stamping CreatedAt / UpdatedAt Fields

Many teams handle timestamp fields in SaveChangesAsync overrides on DbContext. Interceptors offer an equivalent but decoupled alternative — useful when you have multiple DbContext types or when you want to keep the DbContext class itself minimal. The interceptor pattern makes this reusable across multiple contexts without inheritance.

When NOT to Use EF Core Interceptors

Simple Validation

Interceptors are not the right place for business rule validation. If an entity needs to be in a valid state before being saved, that belongs in your domain model or your application layer — not buried in a database pipeline interceptor where the feedback loop is slow and the error reporting is indirect.

FluentValidation behaviours in a MediatR pipeline (see the Zero to Production course, Chapter 11) are a far better home for this concern.

Logging SQL Queries

EF Core has a first-class SQL logging mechanism built into its options: optionsBuilder.LogTo(...) or Serilog integration via AddDbContext. Using IDbCommandInterceptor to log SQL is technically possible but is documented by Microsoft as the wrong tool for this job — the built-in logging mechanisms are more efficient and better integrated with structured logging pipelines.

Complex Business Logic

If your interceptor implementation is making decisions based on business state, calling other services, or branching on domain concepts — stop. Interceptors have no natural way to surface domain exceptions cleanly, they run in a low-level pipeline where debugging is harder, and they create implicit dependencies that are invisible to the reader of your domain code. Move the logic up the stack.

Performance-Critical Paths

Every SaveChanges call runs through registered interceptors synchronously as part of the pipeline. For high-frequency writes where you're already squeezing out every millisecond — bulk insert scenarios, event store appends, high-throughput metrics writes — interceptors add overhead that may not be acceptable. Use ExecuteUpdate and ExecuteDelete (which bypass ChangeTracker and interceptors entirely) for bulk operations where change tracking and auditing are not required.

The Decision Matrix

Registration and Lifecycle Gotcha

Interceptors are registered as services via AddInterceptors(...) in your AddDbContext call. The key mistake teams make: registering an interceptor as a singleton when it has scoped dependencies.

If your audit interceptor needs to resolve the current user's identity from IHttpContextAccessor (a scoped dependency), the interceptor itself must be registered as scoped and resolved from the DI container at DbContext registration time — not instantiated as a singleton. Singleton interceptors with scoped dependencies will throw InvalidOperationException at runtime.

The correct pattern is to retrieve your interceptor from the service provider inside AddDbContext:

builder.Services.AddScoped<AuditInterceptor>();

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    options.UseSqlServer(connectionString)
           .AddInterceptors(sp.GetRequiredService<AuditInterceptor>());
});

This is one of the non-obvious production issues teams hit when first adopting interceptors — and it's covered in detail in the full implementation on Patreon.

Anti-Patterns to Avoid

Interceptor chains with order dependencies. When multiple interceptors are registered, they execute in registration order. If interceptor B depends on state set by interceptor A, you have a hidden ordering dependency that breaks silently when registration order changes. Design each interceptor to be independent.

Throwing exceptions in IDbCommandInterceptor. If your command interceptor throws an unhandled exception, it surfaces as a database error, not a domain error. This makes error handling confusing and breaks the clean exception hierarchy your global error handler relies on.

Using interceptors as a caching layer. Interceptors run on every operation — not selectively. Building cache-aside logic inside an IDbCommandInterceptor that conditionally replaces database calls with cache reads is possible but creates a hidden, hard-to-test caching layer that is disconnected from your application's caching strategy. Use IMemoryCache or HybridCache explicitly at the service layer instead.

Reading ChangeTracker in IDbCommandInterceptor. IDbCommandInterceptor fires at the ADO.NET level, after EF Core has already generated SQL. At that point, ChangeTracker state may not reflect what you expect for all scenarios. Use ISaveChangesInterceptor when you need entity state — it fires earlier in the pipeline and gives you reliable access to the full change set.

Composability With Global Query Filters

EF Core interceptors and Global Query Filters are complementary, not competing. A common production pattern is:

• Global Query Filter on IsDeleted — filters soft-deleted records out of all queries automatically
• ISaveChangesInterceptor — converts EntityState.Deleted to a soft delete before SQL is generated

Together, they make soft delete completely transparent to the rest of the application. Application code reads and writes entities as if they always exist — the infrastructure layer handles the filtering and the conversion. Developers who join the team do not need to know about soft delete logic in their application service code; it is enforced at the infrastructure layer.

Should You Use Interceptors or Override SaveChangesAsync?

Both approaches work for SaveChanges-level concerns. The practical difference:

SaveChangesAsync override is simple, discoverable, and co-located with the DbContext. It works well for single-context applications where a single team owns the DbContext and audit/timestamp logic is stable.

Interceptors are better when:

• You have multiple DbContext types that share the same cross-cutting concern
• You want the concern to be unit-testable independently of the DbContext
• You want the concern to be composable (register different interceptors per environment or feature flag)
• The interceptor has its own dependencies managed by DI

For greenfield enterprise applications, interceptors are the cleaner long-term choice. For existing codebases with established SaveChangesAsync overrides, the migration cost rarely justifies the switch unless you hit a specific pain point.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What is the difference between ISaveChangesInterceptor and IDbCommandInterceptor? ISaveChangesInterceptor fires at the EF Core level — before and after SaveChanges executes, with full access to the ChangeTracker and entity state. IDbCommandInterceptor fires at the ADO.NET level — when the actual SQL command is sent to the database. Use ISaveChangesInterceptor for entity-level concerns (audit trails, soft deletes, timestamps) and IDbCommandInterceptor for SQL-level concerns (query hints, command logging, connection routing).

Do EF Core interceptors work with ExecuteUpdate and ExecuteDelete? No. ExecuteUpdate and ExecuteDelete are bulk operations that bypass ChangeTracker and the SaveChanges pipeline entirely. They generate UPDATE and DELETE SQL directly. Interceptors registered via ISaveChangesInterceptor will not fire for these operations. If your audit requirements cover bulk updates, you need a separate mechanism — either a database trigger or explicit audit records in the calling code.

Can I use interceptors to implement row-level security in EF Core? With caution. You can use IDbCommandInterceptor to append WHERE clauses or IDbConnectionInterceptor to set session context for database-level row security. However, EF Core's Global Query Filters are a cleaner and more maintainable approach for most row-level filtering scenarios. Use interceptors for row-level security only when you need to push enforcement down to the database session level (e.g., for SQL Server Row-Level Security with session context variables).

How do I unit test an EF Core interceptor? Interceptors are standard C# classes that implement an interface — you can instantiate them directly in tests without needing a full DbContext. For ISaveChangesInterceptor tests, you'll want an in-memory SQLite DbContext to exercise the full pipeline. For IDbCommandInterceptor, you can use DbCommandInterceptorTestBase patterns or mock DbCommand. Keeping interceptors small and single-purpose makes them significantly easier to test in isolation.

Will registering multiple interceptors affect performance? Each registered interceptor adds a small overhead to every covered operation. In practice, the overhead of one or two well-written interceptors is negligible compared to network round-trips and query execution time. The performance concern only becomes relevant for very high-frequency bulk write operations — and in those cases, you typically want to use ExecuteUpdate/ExecuteDelete anyway, which bypass interceptors entirely. Profile before optimising; premature interceptor removal is rarely the right call.

Should every ASP.NET Core API use interceptors? Not necessarily. If your application has no cross-cutting database concerns (no audit logging, no soft deletes, no query hints), adding interceptors for their own sake adds complexity without benefit. Start without them. Add them when you have a specific, well-understood requirement that benefits from centralisation at the EF Core pipeline level. The decision guide above is the right checklist: if the use case fits, interceptors are excellent. If it doesn't, pick a more appropriate tool.

The full production implementation of both approaches — complete with service layer integration, unit-of-work variants, and a working test suite — is available on Patreon. The code maps directly to what enterprise .NET teams ship.

Understanding this decision in isolation is useful, but seeing how data access patterns fit into a complete production API — alongside authentication, validation, error handling, and testing — is where it really clicks. That end-to-end context is exactly what the ASP.NET Core Web API: Zero to Production course provides, starting from Chapter 3 where the repository interface in Domain and its EF Core implementation in Infrastructure are covered step by step.

What the Repository Pattern Actually Is (and What It Is Not)

The Repository Pattern introduces an abstraction layer between your domain or application logic and your data access technology. At its core, it is an interface — IProductRepository, for example — that defines data operations (find, add, update, remove) without exposing how those operations are implemented. Your application code depends on the interface; your infrastructure layer provides the EF Core implementation.

What it is not is a generic wrapper over DbSet<T> that mirrors every EF Core operation. That variant — the generic repository — adds indirection without adding abstraction. It does not hide EF Core; it just adds boilerplate between your code and it.

The distinction matters because the strongest arguments against repositories are almost always arguments against generic repositories specifically, not against domain-focused repositories that actually model your bounded context's operations.

What Direct DbContext Means in Practice

Direct DbContext usage means injecting YourDbContext or IDbContextFactory<YourDbContext> into your service, handler, or endpoint — and using LINQ, AsNoTracking(), FindAsync(), and EF Core's full API surface directly, without any wrapping interface.

In small-to-medium codebases, this is honest and practical. EF Core's DbContext is already a Unit of Work; DbSet<T> is already a repository of sorts. Adding another layer on top of it risks hiding the very features — compiled queries, split queries, ExecuteUpdate, ExecuteDelete — that make EF Core 10 worth using in the first place. You can read more about those query performance features in EF Core 10 Query Performance: AsNoTracking, Compiled Queries and Split Queries Explained.

When to Use the Repository Pattern

The case for the repository pattern is strongest in these specific conditions:

Your domain has meaningful aggregate boundaries. If you are practicing Domain-Driven Design and your application has aggregates — Order, Customer, Shipment — then a repository per aggregate root (IOrderRepository, ICustomerRepository) is architecturally correct. The repository is not a data access convenience; it is a domain contract. The implementation happens to use EF Core.

Your application will be tested extensively with unit tests. Mocking DbContext directly is technically possible but ergonomically painful. A repository interface with a clearly defined set of operations (GetByIdAsync, GetPagedAsync, AddAsync) is trivial to mock in Moq or NSubstitute. If your team writes unit tests for application layer handlers or services — as they should — repository interfaces make those tests clean and fast.

You are working in a Clean Architecture or layered structure where Domain and Infrastructure are separate projects. In this structure, Domain cannot reference Infrastructure. The only way to depend on data access from Domain or Application is through an interface. The repository interface lives in Application; the EF Core implementation lives in Infrastructure. This is the pattern used in Clean Architecture with CQRS + MediatR in ASP.NET Core: The Complete Guide (2026) and it is sound.

Your team plans to test data access behaviour in isolation. If you want to write handler unit tests that do not spin up a database, the repository interface is your seam.

When to Use Direct DbContext

Direct DbContext is the right default in these situations:

You are building a small-to-medium API without DDD constraints. If your application is primarily CRUD, your team is small, and your architecture is a single project or a simple layered app without bounded contexts — direct DbContext is cleaner. You get full access to EF Core's API, no abstraction tax, and faster onboarding for new developers.

You are building read-heavy endpoints where query composition matters. Complex filtered, sorted, and paginated queries are harder to model behind a repository interface. With direct DbContext you compose IQueryable<T> chains freely. The moment you put those queries behind an interface, you either leak IQueryable (defeating the abstraction) or you duplicate every filter combination as a new method. Neither is good.

You want to leverage EF Core 10's newest primitives freely. ExecuteUpdate, ExecuteDelete, JSON columns, complex type projections, and new bulk operations do not slot neatly into a Add/Update/Delete repository interface. You can include them, but you either expose them directly (leaking EF Core into the interface) or you miss them entirely.

You are prototyping or iterating quickly. Repository interfaces slow down early development. You should not pay an abstraction tax until you know the shape of your domain.

Side-By-Side Trade-Off Comparison

The Generic Repository Anti-Pattern

The most common mistake teams make is building a GenericRepository<T> that wraps DbSet<T> with methods like GetAll(), GetById(), Add(), Update(), Delete() — and calling it "the repository pattern."

This pattern provides no real abstraction. It does not hide EF Core (it wraps it transparently). It does not model domain operations (CRUD is not a business language). It blocks access to EF Core features (you cannot call ExecuteUpdate through a generic interface without leaking it). And it creates maintenance overhead for no benefit.

If you find yourself writing a generic repository, stop. Either go direct DbContext or commit to domain-specific repository interfaces that model actual aggregate operations.

The Specification Pattern: A Middle Ground

When teams want the testability benefit of an interface but resist full repository abstraction, the Specification Pattern is worth considering. A Specification<T> encapsulates a query predicate, include rules, and ordering. You pass specifications into a thin generic query executor that applies them against IQueryable<T>.

This approach gives you testable, reusable query objects without leaking EF Core into your application layer, while still giving the EF Core implementation the freedom to optimise how the specification is translated into SQL. It is particularly useful for read models in CQRS architectures where the write side uses domain repositories and the read side uses direct queries with specifications.

Decision Matrix: Which Should Your Team Use?

Ask these questions in order:

1. Are you using Clean Architecture or DDD with separate Domain and Infrastructure projects? → Use repository interfaces. They are the only architectural fit.

2. Do you need extensive unit testing of application logic without a database? → Use repository interfaces. The mock-ability benefit is real.

3. Is your application primarily CRUD with few complex domain rules? → Use direct DbContext. There is no abstraction to justify.

4. Do you need full access to EF Core 10 bulk operations and advanced query features? → Favour direct DbContext, or design repository interfaces that expose these operations explicitly.

5. Is your team small and iteration speed matters more than long-term separation? → Start with direct DbContext. You can introduce repository interfaces when complexity demands it.

The answer for most enterprise .NET teams in 2026: use domain-specific repository interfaces when your architecture calls for them, and direct DbContext everywhere else. The mistake is applying one pattern everywhere regardless of context.

What About the Unit of Work Pattern?

EF Core's DbContext is already a Unit of Work. Calling SaveChangesAsync() commits all tracked changes in one transaction. There is rarely a need to wrap this in a separate IUnitOfWork interface unless:

• You are abstracting multiple DbContext instances across bounded contexts in the same transaction

• You need to control SaveChanges behaviour explicitly from the application layer

• Your testing strategy requires mocking the commit boundary separately from repository operations

In most applications, injecting DbContext directly and calling SaveChangesAsync() in your service or handler is perfectly correct. The Unit of Work abstraction becomes valuable when you are orchestrating across multiple aggregates or bounded contexts in a single operation. For deeper context on EF Core performance considerations in high-traffic APIs, see EF Core Performance Tuning Checklist for High-Traffic APIs.

Integrating the Decision Into Your Architecture

If you are starting a new ASP.NET Core API today, consider this layering rule of thumb:

• Single-project or simple layered app: Use DbContext directly in your service classes. Add AsNoTracking() on all read queries. Call SaveChangesAsync() explicitly. Keep it simple.

• Clean Architecture (Domain / Application / Infrastructure / API): Repository interfaces belong in Domain or Application. Implementations belong in Infrastructure. Only the infrastructure project references EF Core.

• CQRS with MediatR: Command handlers typically need repository interfaces (they mutate domain aggregates through repository contracts). Query handlers often use direct DbContext or Dapper — they are read-only and performance-sensitive, so the full query API matters.

This separation is practical and scales well. It also avoids the classic mistake of putting EF Core references in the wrong layer.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

Should I use the repository pattern for every entity in my application? No. Repository interfaces should map to aggregate roots in a DDD context, or to meaningful data access contracts in a layered architecture. Creating a repository for every entity — including simple lookup tables and configuration data — adds overhead without value. Apply repository interfaces where the abstraction boundary genuinely matters.

Does EF Core's DbContext already implement the Repository and Unit of Work patterns? Conceptually yes. DbSet<T> behaves like a repository (it tracks and queries entities of a specific type), and DbContext behaves like a Unit of Work (it tracks all changes and commits them as a single transaction via SaveChangesAsync()). This is why direct DbContext usage is architecturally defensible — you are not bypassing a pattern, you are using the framework's built-in implementation of it.

Can I mix repository pattern and direct DbContext in the same application? Yes, and this is often the right approach. Use repository interfaces for your write model (command side, domain aggregates) where testability and domain isolation matter. Use direct DbContext or Dapper for your read model (query side) where query composition flexibility and performance are the priority. This hybrid is commonly used in CQRS architectures.

What is the performance difference between repository pattern and direct DbContext? The repository interface itself introduces no measurable performance overhead — it is just an interface dispatch. The performance difference, if any, comes from how the implementation is written. A direct DbContext call with AsNoTracking() and ExecuteUpdate is faster than one routed through a repository method that uses full entity tracking unnecessarily — but that is a usage issue, not a pattern issue.

How do I unit test services that use DbContext directly without a repository interface? You have two options. The first is to use EF Core's in-memory provider (UseInMemoryDatabase) or SQLite in-memory mode in your unit tests — these are fast and require no mocking infrastructure. The second is to use Microsoft.EntityFrameworkCore.InMemory as a lightweight test double. Both are valid. The trade-off is that these tests become integration tests (they use the real EF Core stack) rather than pure unit tests. If your team values the distinction, repository interfaces give you a cleaner seam.

Is the repository pattern dead in 2026? No. The generic repository pattern is largely obsolete — it was always a misunderstanding of what the pattern is for. But domain-focused repository interfaces in Clean Architecture and DDD applications remain the correct approach. The pattern is not dead; it is often misapplied. Understanding the difference is what makes the difference.

Does the repository pattern make it easier to swap out EF Core for another ORM? In theory yes — your application code depends only on the interface, not EF Core. In practice, ORM swaps are rare enough that this benefit rarely justifies the abstraction cost on its own. The more practical benefit is test isolation: you can swap a real EF Core repository for a mock in unit tests, which you do constantly. Design for testability first; ORM portability is a secondary benefit.

Understanding ASP.NET Core latency spikes in production means understanding how the runtime manages memory, threads, and I/O concurrency at the same time. These three systems interact in ways that are not always obvious from application code. A GC pause that blocks threads for 80ms can cascade into ThreadPool starvation. An overloaded connection pool creates a queue of waiting requests that all time out together, then recover together — which looks like a spike when it is actually a backlog. Getting to the root cause requires knowing how to observe each layer independently before concluding which one is responsible.

Why Intermittent Spikes Are So Hard to Diagnose

The word "intermittent" is the key signal. Deterministic bugs produce deterministic symptoms. Intermittent spikes mean the problem is load-dependent, resource-dependent, or timing-dependent — it only appears when specific conditions align. The three main culprits behave this way by design:

• GC pressure appears when allocation rates exceed what the background GC can keep up with, triggering blocking Gen 2 or LOH compaction events
• ThreadPool starvation appears when all available threads are blocked waiting on I/O or synchronous operations, forcing new requests to queue until a thread becomes free
• Connection pool exhaustion appears when all database connections in the pool are held by in-flight queries, causing new requests to wait for a connection lease

Each of these creates a distinctive spike profile, and each has a different diagnosis path.

Root Cause 1: Garbage Collector Pressure

The .NET GC is designed to run in the background without stopping application threads. For most workloads it does exactly that. But when allocation rates are high — particularly allocations of objects that survive into Gen 2, or allocations of large objects (greater than 85,000 bytes by default) that go directly to the Large Object Heap — the GC must perform a compacting collection that briefly stops all threads. These stop-the-world pauses typically last anywhere from 10ms to 300ms depending on heap size and fragmentation.

The practical causes of GC pressure in ASP.NET Core APIs include:

String allocations in hot paths. Serialisation, log interpolation, and query string building that runs on every request creates short-lived allocations that age into Gen 1 and Gen 2 faster than expected under load.

Large response buffers. Returning large JSON payloads or loading bulk data into memory in a single call puts objects directly onto the LOH. An 86KB+ array created per request at 500 req/s is a significant LOH pressure source.

LINQ materialisation on every request. Calling .ToList() on large result sets, re-projecting collections, or not using streaming enumerables forces collections to be fully allocated in memory on every request.

Diagnostic approach: Use dotnet-counters to observe GC pause frequency and Gen 2 collection rate in real time:

dotnet-counters monitor --process-id <pid> System.Runtime

Watch for gc-heap-size, gen-2-gc-count, loh-size, and time-in-gc. A time-in-gc above 10% under load is a clear signal of GC pressure causing latency impact.

Fix strategy: Reduce allocation on hot paths. Use ArrayPool<T> and MemoryPool<T> for buffer reuse. Replace string concatenation in loops with StringBuilder or interpolated strings with ReadOnlySpan<char>. Use IAsyncEnumerable<T> for large result sets instead of materialising everything with .ToList(). For JSON serialisation in high-throughput scenarios, System.Text.Json with source generation eliminates much of the per-request allocator pressure.

Root Cause 2: ThreadPool Starvation

The ASP.NET Core Kestrel server processes each request on a ThreadPool thread. The ThreadPool starts with a small number of threads and grows dynamically — but growth is gated by a hill-climbing algorithm that adds one thread per second when it detects contention. Under a sudden traffic spike, this growth rate is far too slow. If existing threads are blocked waiting on synchronous I/O or .Result/.Wait() calls on Tasks, incoming requests queue behind them and start breaching SLA thresholds before the ThreadPool can compensate.

We covered ThreadPool starvation in detail in a dedicated article — but the short version is that two patterns cause almost all starvation cases:

1. Calling .Result or .Wait() on async code — common in legacy middleware, startup code that was "quickly made synchronous," or third-party libraries
2. Sync-over-async in database access — using synchronous EF Core or ADO.NET methods (Find(id) instead of FindAsync(id), SaveChanges() instead of SaveChangesAsync())

Diagnostic approach: dotnet-counters again:

dotnet-counters monitor --process-id <pid> System.Runtime --counters threadpool-queue-length,threadpool-thread-count

If threadpool-queue-length spikes to dozens or hundreds during a latency event while threadpool-thread-count grows slowly, you have starvation. You can also use dotnet-trace to capture a trace during a spike and analyse it with PerfView or SpeedScope to identify exactly which call stacks are blocking threads.

Fix strategy: Audit every synchronous blocking call in the request pipeline. Replace .Result with await. Replace .Wait() with await. Replace synchronous EF Core methods with their async counterparts. For startup code that must run synchronous operations, ensure it runs before app.Run() and not inside middleware handlers. Where a third-party library forces synchronous execution, consider offloading to a dedicated TaskCreationOptions.LongRunning thread rather than using a ThreadPool thread.

Root Cause 3: Database Connection Pool Exhaustion

EF Core and ADO.NET maintain a connection pool — by default a maximum of 100 connections for SQL Server. When all 100 connections are in use, new requests that need a database connection must wait in a queue. If the wait exceeds the connection timeout (default: 15 seconds for SQL Server), the request throws a SqlException with the message "Timeout expired. The timeout period elapsed prior to obtaining a connection from the pool." If it does not exceed the timeout, the request simply spends its entire latency budget waiting for a connection to become free — which is what creates the spike.

We covered this root cause in detail in EF Core Connection Pool Exhaustion in ASP.NET Core. The common triggers are:

• Long-running queries holding connections. Connections are only returned to the pool once the query is complete and the DbContext is disposed. A slow query that takes 3 seconds holds a connection for 3 seconds — at 50 concurrent slow requests, the pool is saturated.
• DbContext not disposed promptly. In non-DI scenarios or manual DbContext instantiation, connections can be held far beyond their useful lifetime.
• N+1 query patterns. Loading a parent entity then querying children one at a time in a loop multiplies the connection hold time per request, saturating the pool faster than expected.
• Missing AsNoTracking() on read queries. EF Core tracking overhead keeps contexts alive longer than necessary in scenarios where writes never happen.
• Too many concurrent operations per request. Parallelising DbContext operations (e.g., Task.WhenAll with multiple queries) on the same context instance causes errors; spreading them across multiple contexts simultaneously exhausts the pool.

Diagnostic approach: Monitor the Microsoft.EntityFrameworkCore.Database.Connection category with structured logging enabled at Information level, or instrument your application with OpenTelemetry to track active connection counts. In SQL Server, the DMV sys.dm_exec_requests shows active connections and their wait states. Azure SQL provides this through Query Performance Insight.

Fix strategy: Increase awareness of query duration in hot paths. Add AsNoTracking() on all read-only queries. Resolve N+1 patterns with .Include() or split queries. Review your Max Pool Size connection string setting — increasing from 100 to 200–300 is often appropriate for high-traffic APIs, but treat this as a palliative measure, not a fix. The real fix is shortening query duration and reducing unnecessary holds.

How the Three Root Causes Interact

What makes production latency spikes particularly difficult to diagnose is that these three causes interact. A GC pause that blocks all threads for 50ms causes incoming requests to queue. If those queued requests all proceed simultaneously once threads are released, they saturate the connection pool together. The connection pool exhaustion then holds the connections long enough that threads block waiting for results, which contributes to a secondary ThreadPool pressure event. The result is a cascade — a short GC pause triggers a spike that looks far worse than the GC event itself would suggest.

This is why diagnosing with a single metric is unreliable. Observing all three — GC pause frequency, ThreadPool queue depth, and active database connection count — simultaneously during a latency event gives you a causal chain to work from. dotnet-counters and dotnet-trace provide exactly this visibility without requiring application restarts or code changes.

A Diagnostic Playbook for Production Latency Spikes

When a latency spike event is in progress or has just occurred:

Step 1 — Confirm the scope. Check your APM dashboard (Application Insights, Datadog, Grafana + OpenTelemetry) for which endpoints are affected. A spike isolated to one endpoint strongly suggests a specific slow query or blocking call. A spike across all endpoints suggests a runtime-level cause (GC or ThreadPool).

Step 2 — Check GC metrics. If you have live metrics available, look at time-in-gc and gen-2-gc-count. A spike in Gen 2 collections coinciding with the latency event confirms GC pressure. Run dotnet-counters against the live process if metrics are not already instrumented.

Step 3 — Check ThreadPool metrics. Look at threadpool-queue-length. A queue length that spikes significantly during the latency window — with slow thread count growth — confirms starvation. Look for synchronous blocking call stacks in a dotnet-trace capture.

Step 4 — Check database connection metrics. Query sys.dm_exec_requests or your equivalent. Look for a large number of requests in WAITFOR or SLEEP states, or requests that have been active for many seconds. Enable EF Core connection logging at Debug level temporarily if you need per-query visibility.

Step 5 — Cross-correlate timing. Map the timestamps of each signal against the p99 response time timeline. Whichever signal appears first is the triggering cause. The others may be downstream effects.

Prevention: Reducing Spike Frequency at the Source

Beyond diagnostics, three architectural decisions significantly reduce the frequency and severity of latency spikes:

Server GC over Workstation GC. Container deployments that do not explicitly configure GC mode can default to Workstation GC, which uses fewer threads and pauses more frequently. Set System.GC.Server=true in runtimeconfig.json for production ASP.NET Core workloads. Alternatively, set the environment variable DOTNET_GCConserveMemory to tune memory vs latency trade-offs.

Minimum ThreadPool threads. The ThreadPool default minimum for many environments is set to the number of logical processors. Under burst traffic, this is too low. Use ThreadPool.SetMinThreads(workerThreads, completionPortThreads) at startup to pre-warm enough threads to absorb an initial burst without triggering the slow hill-climbing growth delay. Be conservative — excessively high minimums waste memory.

Connection pool sizing matched to workload. Profile your average query duration under load. Multiply expected concurrency by average query duration in seconds to estimate your target pool size. Add a safety margin. Set Max Pool Size in your connection string accordingly — but pair it with query performance work rather than relying solely on a larger pool.

What Should Not Be Your Diagnostic Tool

A few approaches that are commonly tried but are poor diagnostic choices:

Restarting the process. A restart clears the symptom temporarily but tells you nothing about the cause, and risks data integrity if connections are mid-transaction.

Adding more replicas without diagnosis. Horizontal scaling can reduce per-instance load but does not fix a structural issue. GC pressure from large allocations will affect every replica. ThreadPool starvation from synchronous code will affect every replica. More instances of a broken design is still a broken design.

Increasing timeouts. Raising connection timeout, command timeout, or Kestrel request timeout delays failure but does not prevent queuing. It often makes spikes worse by holding resources longer before releasing them.

FAQ

What is the most common cause of intermittent latency spikes in ASP.NET Core production APIs?

The most common single cause is ThreadPool starvation from synchronous blocking calls — typically .Result, .Wait(), or synchronous EF Core operations used in code paths that run under real concurrent load. This is common in APIs that were progressively async-ified from a synchronous codebase and still contain legacy synchronous sections in middleware or service layers. GC pressure from large or frequent allocations is the second most common cause.

How do I know if my ASP.NET Core latency spikes are caused by GC or something else?

The clearest signal is correlation between gen-2-gc-count and time-in-gc metrics and the timestamps of your latency events. If the GC pause duration and frequency spike at exactly the same time as your p99 latency rises, GC is the cause. Use dotnet-counters to observe these metrics live. If the GC metrics look healthy during a latency event, shift your investigation to ThreadPool queue depth and connection pool wait times.

Can GC pauses really cause noticeable latency spikes in production?

Yes. In APIs with high allocation rates or significant LOH usage, stop-the-world Gen 2 collections can pause all threads for 50–300ms depending on heap size. At p99, this is highly visible. The effect is amplified when concurrent requests are queued during the pause and then all proceed simultaneously when threads resume — creating a burst that itself strains the ThreadPool and connection pool.

What is the recommended way to diagnose a live ASP.NET Core production latency spike?

Use dotnet-counters to monitor key runtime counters live against the process — specifically threadpool-queue-length, gen-2-gc-count, time-in-gc, and loh-size. If the spike is reproducible, capture a dotnet-trace during the event and analyse it in PerfView or SpeedScope to identify the blocking call stacks. For database-related spikes, query your database engine's active request DMVs or query the activity log from your APM tool. Microsoft's .NET diagnostics documentation provides the full reference for these tools.

How does the dotnet-trace tool help identify latency root causes?

dotnet-trace captures a continuous trace of .NET runtime events — including GC events, ThreadPool events, and method-level timing — with very low overhead. After a spike, you can load the trace file in PerfView and look at the Flame Graph view to identify which methods are spending the most time executing or waiting. Call stacks that show .Result or .Wait() at the top of blocked thread stacks are the classic ThreadPool starvation signature. Concentrated Gen 2 GC events clustered around the spike timestamp confirm GC pressure.

How many database connections should my ASP.NET Core API pool have configured?

The right pool size depends on your query duration and concurrency profile. A rough formula: Max Pool Size = (average concurrent requests) × (average query duration in seconds) × safety_factor(1.5). For most production APIs serving a few hundred concurrent users with sub-100ms queries, the default of 100 is adequate if queries are written efficiently. If you are regularly saturating the pool, start by optimising slow queries and adding AsNoTracking() to read-only paths before increasing Max Pool Size.

Is it worth increasing the minimum ThreadPool threads in production?

Yes, for APIs that experience burst traffic. Pre-warming threads with ThreadPool.SetMinThreads() at startup avoids the slow hill-climbing growth delay when traffic spikes. A reasonable starting point is setting the minimum to the number of logical processors multiplied by 4–8, then measuring the impact on burst-traffic p99 latency. This does not fix starvation caused by synchronous blocking code — it only reduces the ramp-up delay when load increases suddenly.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

If you want to see this pattern applied inside a full production-grade ASP.NET Core codebase — with every layer wired together and tested — the complete source code and worked examples are on Patreon, annotated and ready to run.

The pattern takes its name from the strangler fig tree, which grows around an existing host tree, gradually taking over its structure until the original tree can be removed entirely. Applied to software, the new ASP.NET Core system is built alongside the legacy application — first intercepting specific routes, then more, until the legacy system handles nothing and can be decommissioned.

What Problem Does the Strangler Fig Pattern Solve?

Enterprise .NET teams face a common dilemma: the legacy system is too risky to touch, but also too expensive to leave alone. It might be a classic ASP.NET Framework MVC application running on IIS, a .NET Framework Web API that predates dependency injection, or a monolith with tightly coupled business logic and no automated tests.

A full rewrite forces you to pause feature delivery, maintain two codebases in parallel under pressure, and go live with an untested replacement. Most big-bang rewrites fail — not because of technical incompetence, but because the risk accumulates and the deadline pressure shortcuts the quality.

The Strangler Fig pattern avoids this by making modernization a series of small, independently deployable steps. Each step ships. Each step reduces legacy surface area. The system is always in production and always functional.

How the Strangler Fig Pattern Works

The mechanics are straightforward: a facade layer sits in front of both the legacy and new systems. Every incoming request is intercepted at this facade. If the new system has a working implementation for that endpoint, the request is routed to the new system. If not, the request passes through to the legacy system unchanged.

The facade grows over time. You migrate one endpoint or one domain. You verify it works. You update the routing rules to stop forwarding that endpoint to legacy. You repeat. Over months — or years, for large systems — the legacy system handles progressively fewer requests until the routing table no longer contains any legacy routes and the legacy system is taken offline.

In the ASP.NET Core ecosystem, YARP (Yet Another Reverse Proxy) is the standard tool for implementing the facade. YARP is a Microsoft-maintained, ASP.NET Core–native reverse proxy that runs as standard middleware. It can route, transform, and load-balance requests based on route patterns, headers, or custom predicates — and it integrates with the rest of the ASP.NET Core pipeline cleanly.

When to Use It

The Strangler Fig pattern is the right choice when:

The legacy system is live and cannot afford downtime. If you cannot take the system offline, you cannot do a big-bang replacement. The Strangler Fig lets you migrate with zero planned downtime.

The legacy system has no adequate test coverage. Migrating piece by piece allows you to write tests for each piece as you move it. You cannot safely test a full rewrite of an untested system.

The business still needs features during migration. The new system can deliver new functionality while the migration continues in parallel. Feature delivery does not pause.

Teams are small and migration must be incremental. A two-person team cannot rewrite a 100K-line system in six months. They can migrate ten endpoints a sprint while shipping new features.

The technology stack needs to change, not just the architecture. Moving from ASP.NET Framework 4.x to ASP.NET Core, or from synchronous request handling to async, is far less risky when done one domain at a time.

When Not to Use It

When the legacy system is unmaintainable and tightly coupled. If a single endpoint touches forty stored procedures and three legacy services, migrating it in isolation is not straightforward. The Strangler Fig works best when domain boundaries can be drawn.

When the legacy system's data model is the actual problem. Migrating endpoints does not fix a fundamentally broken data schema. If the schema needs major restructuring, that work must run in parallel — and may require a different strategy (event-driven migration, dual-write patterns, or schema versioning).

When the team lacks operational maturity to run two systems simultaneously. Running legacy and new in parallel means two sets of deployments, two sets of monitoring, two sets of support. If your team cannot manage that operational overhead, the pattern adds more risk than it removes.

When the window for migration is very short. The Strangler Fig pattern is a long-game strategy. If you have three months and need the full system migrated, you may need a more aggressive approach — with higher risk.

Core Concepts

The Facade (YARP as the Router)

YARP acts as the strangler facade. It receives every inbound request and decides where to send it based on route configuration. Early in a migration, most routes point to the legacy system. As endpoints are migrated, their routes are updated to point to the new ASP.NET Core application.

YARP configuration can be code-based or file-based (appsettings.json). The key capability is route matching — you can match by path prefix, exact path, HTTP method, headers, or custom predicates. This granularity is what makes endpoint-by-endpoint migration practical.

A useful pattern is to use a YARP cluster named legacy that points to your on-premise IIS-hosted legacy application and a cluster named new-api that points to your new ASP.NET Core service. Each route entry specifies which cluster handles that request. Migrating an endpoint is as simple as changing one route's ClusterId from legacy to new-api — no downtime, just a config push.

Migrating Domain by Domain, Not Layer by Layer

The most common Strangler Fig mistake is trying to migrate infrastructure layers horizontally — "we'll migrate all controllers first, then the services, then the database access." This approach produces nothing deployable for months.

The correct strategy is vertical slicing: pick one complete domain — for example, product catalogue read operations — and migrate the full stack for that domain: the endpoint, the application logic, the data access, and the tests. Once that slice is working and routed through the new system, start the next slice. Each slice is independently valuable and independently deployable.

Dual-Write and Data Synchronisation

The most technically demanding aspect of a Strangler Fig migration is usually data. If the legacy and new systems share a database, you may be able to migrate endpoints without data changes initially — both systems read and write the same tables. If you want to move to a new schema or a new database in the new system, you need a dual-write period where changes are written to both stores and a reconciliation process keeps them in sync.

This is where the complexity genuinely lives. The Strangler Fig pattern does not prescribe how to solve data migration — that is a separate concern. But it is worth naming: you will need a data migration strategy, and the pattern works best when that strategy is planned before migration begins.

Feature Flags as a Traffic Controller

Feature flags can complement YARP routing in nuanced ways. Rather than hardcoding which cluster a route points to in YARP configuration, you can implement a custom YARP middleware that checks a feature flag per request. This allows you to:

• Route a percentage of traffic to the new system (canary release)
• Route traffic by tenant, user role, or region
• Roll back a specific endpoint to legacy without a deployment

ASP.NET Core's built-in feature management (Microsoft.FeatureManagement) integrates naturally with this approach.

Implementation Sketch

Setting up YARP as a strangler facade involves three key steps.

Step 1: Add YARP to your new ASP.NET Core host. YARP is available via the Yarp.ReverseProxy NuGet package and is registered as middleware in Program.cs alongside your new API routes. Both the new controllers and the YARP forwarder run in the same process.

Step 2: Configure routes and clusters. Your appsettings.json (or code-based configuration) maps route patterns to clusters. Migrated endpoints point to the new-api cluster. Everything else points to legacy. As you migrate, you move routes from one cluster to the other.

Step 3: Establish an observability boundary. Add structured logging and distributed tracing at the YARP middleware level. You need to know, for every request, which system handled it. This is non-negotiable — it is how you validate that legacy traffic is declining and new-system traffic is increasing as expected.

Trade-offs

The Circuit Breaker pattern integrates naturally with the facade layer — if the legacy system becomes unavailable, YARP can fail fast and the new system can return a graceful fallback response rather than timing out. For teams also working on ACL layers between domains, the Anti-Corruption Layer pattern is a direct complement to Strangler Fig when legacy domain models need translation before entering the new system. The Circuit Breaker pattern in ASP.NET Core covers the resilience side in detail.

Anti-Patterns to Avoid

Keeping the facade forever. The facade is temporary scaffolding. Teams that stop the migration partway through end up with a permanent proxy that adds latency and complexity without completing the goal. Decide upfront what "done" looks like and treat it as a hard milestone.

Migrating without feature parity validation. Before updating a route in YARP to point to the new system, run both systems in parallel on the same request shape and compare responses (shadow testing or traffic mirroring). Skipping this step leads to silent regressions.

Migrating only the happy path. Legacy systems often have years of edge-case handling baked in — error responses, content negotiation quirks, unusual header behaviour. Your new implementation needs to match that behaviour, not just the success path.

Treating data migration as an afterthought. Many migrations stall because the endpoint logic is migrated but the database is not. Plan data migration upfront, even if execution is deferred.

Letting the legacy codebase continue to grow during migration. Every new feature added to the legacy system is another thing to migrate. If migration is underway, new feature work should go into the new system — even if the facade is not yet routing that domain.

☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!

FAQ

What is the Strangler Fig pattern in ASP.NET Core? The Strangler Fig pattern is an incremental migration strategy where a new ASP.NET Core system is built alongside a legacy application. A reverse proxy facade (typically YARP in .NET) intercepts all requests and routes each one to either the new or legacy system based on which endpoints have been migrated. The legacy system is decommissioned once all routes have been moved to the new system.

When should I use the Strangler Fig pattern instead of a full rewrite? Use it when your legacy system is live and cannot afford downtime, when the team is small and migration must happen alongside feature delivery, when the legacy codebase lacks test coverage, or when risk tolerance is low. A full rewrite is appropriate only when the legacy system is truly unmaintainable and all stakeholders accept the risk of a big-bang cutover.

How does YARP fit into the Strangler Fig pattern in .NET? YARP (Yet Another Reverse Proxy) is a Microsoft-maintained ASP.NET Core library that acts as the strangler facade. It runs as middleware in an ASP.NET Core host and routes incoming requests to either the legacy cluster or the new API cluster based on configurable route rules. Migrating an endpoint from legacy to new is as simple as updating a route's cluster target in YARP configuration — no code change required.

How do I handle database migration with the Strangler Fig pattern? The pattern does not prescribe a data migration strategy. Common approaches include sharing a single database between legacy and new systems during migration (simplest, works when the schema is not changing), dual-write with synchronisation (required when the new system uses a different schema), and event-driven migration using the outbox pattern to propagate changes between stores. Plan data migration before starting endpoint migration — it is almost always the most complex part.

Can I use feature flags with the Strangler Fig pattern in ASP.NET Core? Yes. Custom YARP middleware can evaluate feature flags (via Microsoft.FeatureManagement) to decide which cluster a request is forwarded to. This enables canary releases (route 5% of traffic to the new system), tenant-based routing, and instant rollback without a deployment — just flip the flag.

How do I validate that the new system behaves identically to the legacy system? Shadow testing (traffic mirroring) is the most reliable approach. Route production traffic to both systems simultaneously, compare responses, and log discrepancies — without affecting the user. YARP supports request duplication via custom middleware. This should be done before updating any route to actively serve users from the new system.

What is the typical timeline for a Strangler Fig migration? There is no universal answer — it depends on the size of the legacy system, team capacity, and how cleanly the domain boundaries can be drawn. Small APIs (20–50 endpoints) can be migrated in a few months. Large monoliths may take 12–24 months. The key is to keep migration slices small, ship each one independently, and maintain organisational commitment for the full duration.