Interview Field Guide 2026

Two runtimes and one contract

The names are confusing because Microsoft reused the ".NET" brand for very different things. A simple way to sort them: there are two runtime families (the legacy Windows-only .NET Framework and the modern cross-platform .NET) plus one specification (.NET Standard) that defined an API surface both could implement.

How we got here

flowchart LR
  NF[".NET Framework 1.0 to 4.8.1 - Windows only"]
  NC[".NET Core 1.0 to 3.1 - cross-platform"]
  N5[".NET 5 - Core renamed, 2020"]
  N8[".NET 8 LTS"]
  N9[".NET 9 STS"]
  N10[".NET 10 LTS - Nov 2025"]
  N11[".NET 11 STS - Nov 2026"]
  NS[".NET Standard 2.0 - shared API contract"]
  NC --> N5 --> N8 --> N9 --> N10 --> N11
  NS -.->|"implemented by"| NF
  NS -.->|"implemented by"| NC
  NS -.->|"implemented by"| N10

In 2016 Microsoft could not make .NET Framework cross-platform without breaking millions of Windows apps, because it is installed machine-wide, updated in place and tied to Windows (IIS, the registry, COM). So it built .NET Core alongside it: modular, side-by-side, open source and much faster. When Core 3.1 had absorbed most of what people needed (including WinForms and WPF on Windows), the next release was called .NET 5. "Core" was dropped to signal that this is now the .NET. Version 4 was skipped to avoid confusion with .NET Framework 4.x. ASP.NET Core and EF Core kept the "Core" suffix to tell them apart from ASP.NET 4.x (System.Web) and Entity Framework 6.

.NET Framework: what it still is, and what it isn't

.NET Framework 4.8.1 is the last version. Since 4.5.2 it has been defined as a component of Windows, so 4.6.2 through 4.8.1 are supported for as long as the Windows version they run on is supported. You get security and reliability fixes, but no new APIs, runtime features or performance work. Several technologies were never ported to modern .NET:

• ASP.NET Web Forms and the System.Web pipeline (replaced by ASP.NET Core, Razor Pages and Blazor).
• WCF server (the community CoreWCF project fills part of the gap; gRPC is the usual replacement). Windows Workflow Foundation.
• AppDomains (only one exists in modern .NET; use AssemblyLoadContext for isolation), .NET Remoting and Code Access Security.

Large Framework apps are usually migrated incrementally (strangler fig): a new ASP.NET Core app sits in front, uses YARP to forward not-yet-migrated routes to the old app, and takes over endpoints one by one. System.Web adapters share session and authentication in the meantime.

Modern .NET: cadence, support and deployment

• Yearly releases every November. Even-numbered versions are LTS (3 years of support). Odd-numbered ones are STS, which now get 2 years (extended from 18 months starting with .NET 9). That is why .NET 8 and .NET 9 end support on the same day.
• Side-by-side. Several runtimes can be installed at once. An app is either framework-dependent (uses a shared runtime and rolls forward to the latest installed patch) or self-contained (ships its own runtime). Native AOT goes further and produces a single native binary.
• One TFM family. net10.0 covers web, console and libraries. OS-specific suffixes (net10.0-windows, net10.0-android, net10.0-ios) add platform APIs such as WPF/WinForms or mobile bindings.

.NET Standard: a contract, not a runtime

Before .NET 5 there were several runtimes: Framework, Core, Mono/Xamarin and Unity. A library author needed one target that worked on all of them. .NET Standard solved this with a versioned reference assembly (netstandard.dll) that lists APIs. Each runtime version declares which Standard version it implements. Higher versions have more APIs and are implemented by fewer platforms:

• netstandard2.0: implemented by .NET Framework 4.6.1+ (4.7.2+ recommended in practice), .NET Core 2.0+, all .NET 5+ versions, Mono and Unity. This is the bridge target and the only Standard version still worth choosing.
• netstandard2.1: .NET Core 3.0+ and Mono, but not .NET Framework. That removes its main reason to exist.
• There will be no new versions after 2.1. In .NET 5+, the net10.0 TFM is the contract, and newer APIs ship with the platform each year instead of waiting for a cross-runtime standardization process.

A typical reusable NuGet library multi-targets: netstandard2.0 for reach, plus a modern TFM to light up faster APIs.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- In-box on net10.0, a package on netstandard2.0 -->
  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
    <PackageReference Include="System.Text.Json" Version="10.0.0" />
  </ItemGroup>
</Project>

using System.Security.Cryptography;

namespace Contoso.Common;

public static class Hashing
{
    public static string Sha256Hex(byte[] data)
    {
#if NET5_0_OR_GREATER
        // Allocation-friendly APIs that only exist in modern .NET
        return Convert.ToHexString(SHA256.HashData(data));
#else
        using var sha = SHA256.Create();
        return BitConverter.ToString(sha.ComputeHash(data)).Replace("-", "");
#endif
    }
}

What to target in 2026: a decision guide

The big picture: CLI is the spec, CLR is the engine

The Common Language Infrastructure (CLI), standardized as ECMA-335, defines four things: a type system (CTS), a metadata format, an instruction set (CIL/IL), and a Virtual Execution System that runs it. The CLR is Microsoft's execution system. In modern .NET this is CoreCLR. Mono and the Native AOT runtime are other implementations of the same model. Because every compiler targets the same IL and type system, a library written in one .NET language works from any other with no glue code.

flowchart TB
  CS["CSharp source"] --> IL["IL + metadata in an assembly"]
  FS["FSharp source"] --> IL
  VB["Visual Basic source"] --> IL
  IL --> CLR["CLR - class loader, JIT, GC, exceptions, threads"]
  BCL["BCL - System.* libraries"] --> CLR
  CLR -->|"interop"| NAT["Native code - OS APIs, C and C++ libraries"]
  CLR --> OS["Operating system"]

CLR: what "the runtime" actually does

• Loading and binding: finds assemblies (via the app's .deps.json and the shared framework), loads them into an AssemblyLoadContext and builds in-memory type structures (method tables).
• Type safety: every object knows its exact type, casts are checked, array accesses are bounds-checked, and memory is not reinterpreted unless you opt into unsafe.
• Compilation: JIT-compiles IL to machine code per method, with tiered compilation and Dynamic PGO (or uses precompiled ReadyToRun/Native AOT code).
• Memory management: allocation on the managed heap and a generational, compacting garbage collector.
• Exceptions, threads and the thread pool: structured exception handling across languages, plus the thread pool that powers async/await.
• Interop, reflection and diagnostics: P/Invoke and COM marshalling, metadata-driven reflection, and the debugger, profiler and EventPipe APIs that tools like dotnet-trace use.

What it no longer does: Code Access Security and multiple AppDomains are gone in modern .NET. Today the security boundary is the OS process or container, not the runtime.

CTS: one type system for every language

The Common Type System defines how types are declared and how they behave at run time:

• Two fundamental categories: value types (structs, enums, primitives, copied by value, inline storage) and reference types (classes, interfaces, delegates, arrays, strings, which live on the GC heap and are accessed by reference).
• Five kinds of types: classes, structs, enums, interfaces and delegates. Members are fields, methods, properties, events, constructors and nested types.
• Single inheritance of implementation, multiple interface implementation, and a single root: System.Object. Because value types also derive from object (via System.ValueType), the CTS defines boxing so a value type can be treated as an object.
• Accessibility levels such as family (C# protected), assembly (internal), family-or-assembly (protected internal) and family-and-assembly (private protected).

Language keywords are just aliases for CTS types. C# int, F# int and VB Integer all compile to System.Int32, so a method taking int in C# is callable from VB with no conversion.

int a = 42;
System.Int32 b = a;                   // identical type, the keyword is only an alias
Console.WriteLine(a.GetType());       // System.Int32

object boxed = a;                     // boxing: copies the value into a heap object
int unboxed = (int)boxed;             // unboxing: type-checked copy back
Console.WriteLine(typeof(int).IsValueType);    // True
Console.WriteLine(typeof(string).IsValueType); // False

CLS: the interoperability contract for public APIs

The CTS is richer than what every language can express. The Common Language Specification is a set of rules for the public surface of a library so that any CLS-consuming language can use it. Some typical rules:

• Unsigned integers other than byte (ushort, uint, ulong) should not appear in public signatures.
• Identifiers must differ by more than case (Total and total as two public members break case-insensitive languages like VB).
• Unmanaged pointer and function pointer types are not CLS-compliant.

[assembly: CLSCompliant(true)]   // ask the compiler to check the public surface

namespace Contoso.Metrics;

public class Counter
{
    private uint _value;                          // fine: private members are not checked

    public uint Value => _value;                  // warning CS3003: type is not CLS-compliant

    [CLSCompliant(false)]
    public void Add(uint delta) => _value += delta;   // explicitly opted out

    public void Add(long delta) => _value += checked((uint)delta); // compliant alternative
}

In 2026 the CLS matters mainly for public SDKs and libraries consumed by VB.NET or F# teams. Most application code never enables the check.

BCL, FCL and the shared frameworks

The Base Class Library is the core set of types: primitives, string, collections, LINQ, I/O, threading and tasks, HttpClient, System.Text.Json, cryptography and more. Physically, the types the runtime depends on most (Object, String, Span<T>, ...) live in System.Private.CoreLib, and the rest is spread across many assemblies. You compile against reference assemblies such as System.Runtime.dll, which use type forwarding to point to the real implementation. Historically, the FCL (Framework Class Library) meant the BCL plus everything above it (ASP.NET, WinForms, WPF, ADO.NET). In modern .NET that role is played by the shared frameworks Microsoft.NETCore.App, Microsoft.AspNetCore.App and Microsoft.WindowsDesktop.App, plus NuGet packages such as Microsoft.Extensions.*.

Managed vs unmanaged code

Managed code runs under the control of the runtime. Its memory is garbage-collected, its types are verified, exceptions unwind safely, and metadata describes everything, which enables reflection, serializers and debuggers. Unmanaged code is native machine code (C, C++, Rust, OS APIs) that manages its own memory. You cross the boundary with P/Invoke, COM interop or function pointers. Since .NET 7, the [LibraryImport] source generator produces the marshalling code at compile time, which is faster and works with Native AOT.

using System.Runtime.InteropServices;

// Requires <AllowUnsafeBlocks>true</AllowUnsafeBlocks> because the generated stub uses unsafe code.
internal static partial class User32
{
    [LibraryImport("user32.dll", EntryPoint = "MessageBoxW", StringMarshalling = StringMarshalling.Utf16)]
    internal static partial int MessageBox(nint hWnd, string text, string caption, uint type);
}

The GC only knows about managed memory. File handles, sockets and native buffers are invisible to it, which is why IDisposable, using and SafeHandle exist: they release native resources deterministically, and finalizers are only a safety net. Two nuances interviewers like: unsafe C# code is still managed (it runs on the CLR, just without verification), and a Native AOT binary is also still managed code. It has a GC, type safety and exceptions. The only difference is that it was compiled ahead of time instead of by a JIT.

Anatomy of a .dll

A managed assembly uses the same PE/COFF container format as native Windows binaries, even on Linux and macOS. The difference is a CLI header that points the runtime at the managed parts:

Debug symbols live in a separate portable .pdb (or are embedded). In modern .NET, MyApp.dll is not started directly. The native apphost (MyApp.exe or MyApp), or dotnet MyApp.dll, starts the host. The host reads MyApp.runtimeconfig.json (which runtime to use) and MyApp.deps.json (where each dependency is), starts CoreCLR, and loads your assembly.

flowchart LR
  P["csproj and source files"] -->|"dotnet build"| D["Contoso.Billing.dll - IL, metadata, manifest"]
  D -->|"dotnet pack"| N["Contoso.Billing.nupkg"]
  N -->|"push"| F[("NuGet feed")]
  F -->|"restore"| G["Global packages folder"]
  G --> A["obj/project.assets.json"]
  A -->|"build / publish"| O["bin: dlls + deps.json + runtimeconfig.json"]
  O -->|"host starts CoreCLR"| R["Running app"]

Looking inside: metadata is the real API

Metadata is what makes .NET self-describing. Compilers use it instead of header files, reflection and the JIT read it, and tools can inspect it without running any code:

using System.Reflection;
using System.Reflection.Metadata;
using System.Reflection.PortableExecutable;

// 1) Reflection: load the assembly and read its manifest
Assembly asm = typeof(InvoiceCalculator).Assembly;
AssemblyName id = asm.GetName();
Console.WriteLine($"{id.Name} v{id.Version} culture='{id.CultureName}'");
Console.WriteLine(asm.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion);
foreach (AssemblyName r in asm.GetReferencedAssemblies())
    Console.WriteLine($"  references {r.Name} {r.Version}");

// 2) System.Reflection.Metadata: read the raw tables without loading anything
using var stream = File.OpenRead("Contoso.Billing.dll");
using var pe = new PEReader(stream);
MetadataReader md = pe.GetMetadataReader();
foreach (TypeDefinitionHandle h in md.TypeDefinitions)
{
    TypeDefinition t = md.GetTypeDefinition(h);
    Console.WriteLine($"{md.GetString(t.Namespace)}.{md.GetString(t.Name)}");
}

For day-to-day inspection, ILSpy or dotPeek decompile IL back to C#, which is invaluable when you need to know what a library actually does.

Identity and the three version numbers

An assembly's identity is name + version + culture + public key token. There are three version attributes, and they are often confused:

• AssemblyVersion: part of the identity. It is recorded in every referencing assembly's manifest and used for binding.
• FileVersion: the Win32 file version shown in Explorer. The runtime ignores it.
• InformationalVersion: free-form product version (e.g. 2.3.1+4f1c2ab). Since the .NET 8 SDK it includes the source commit by default. The runtime ignores it too.

The NuGet package version (SemVer) is a fourth, separate number. By default the SDK derives all of them from <Version>.

<PropertyGroup>
  <TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>
  <PackageId>Contoso.Billing</PackageId>
  <Version>2.3.1</Version>                    <!-- package version, default for the rest -->
  <AssemblyVersion>2.0.0.0</AssemblyVersion>  <!-- binding identity: bump on breaking majors -->
  <FileVersion>2.3.1.0</FileVersion>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>
<ItemGroup>
  <InternalsVisibleTo Include="Contoso.Billing.Tests" />
</ItemGroup>

Binding differs by runtime. .NET Framework binds strictly to the referenced version, which is where binding redirects in app.config came from. Modern .NET builds a list of trusted assemblies from deps.json and accepts the version found there if it is the same or higher than the referenced one, so binding redirects are gone. Strong naming (signing with a key) gives no benefit on .NET Core/.NET 5+: the runtime neither validates the signature nor uses it for binding. It only matters if .NET Framework apps consume your library. This is why popular libraries keep AssemblyVersion stable across minor releases (Newtonsoft.Json stays at 13.0.0.0 for every 13.x release).

Namespaces vs assemblies

• A namespace is a compile-time naming convenience. At run time it is just a prefix of the type's full name.
• An assembly is a physical boundary: internal means "visible inside this assembly" (opened selectively with InternalsVisibleTo), and versioning and deployment happen per assembly.
• The mapping is many-to-many. For example, the namespace Microsoft.Extensions.DependencyInjection has types in both ...DependencyInjection.Abstractions.dll and ...DependencyInjection.dll.
• Runtime type identity is assembly + full name. Load the same assembly twice into two AssemblyLoadContexts and you get the famous "cannot cast Foo to Foo" error.

Practical consequence: a using directive never fixes "type not found". You need a reference to the assembly (usually via a package) that contains the type.

NuGet packages: what's in a .nupkg

Contoso.Billing.2.3.1.nupkg                (a zip archive)
  Contoso.Billing.nuspec                   id, version, dependencies per TFM, license, repo URL
  lib/netstandard2.0/Contoso.Billing.dll   implementation for netstandard2.0 consumers
  lib/net10.0/Contoso.Billing.dll          implementation for net10.0+ consumers
  lib/net10.0/Contoso.Billing.xml          XML docs for IntelliSense
  analyzers/dotnet/cs/Contoso.Billing.Generators.dll   optional analyzer / source generator
  buildTransitive/Contoso.Billing.targets  optional MSBuild hooks
  runtimes/linux-x64/native/libcontoso.so  optional RID-specific native asset

On restore, NuGet resolves the dependency graph (direct references win; otherwise the lowest version that satisfies all ranges), downloads packages into the global packages folder (~/.nuget/packages), and writes obj/project.assets.json. At build time MSBuild picks the nearest compatible TFM folder. A net10.0 app uses lib/net10.0 if present, otherwise lib/net8.0, otherwise lib/netstandard2.0. dotnet list package --include-transitive and dotnet nuget why show where a transitive package comes from.

A realistic .NET 10 Program.cs

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

// ---- 1. Configuration and options -----------------------------------
builder.Services.AddOptions<PaymentOptions>()
    .BindConfiguration(PaymentOptions.SectionName)
    .ValidateDataAnnotations()
    .ValidateOnStart();                                  // fail fast on bad config

// ---- 2. Services (DI registrations) ---------------------------------
builder.Services.AddDbContext<ShopDbContext>(o =>
    o.UseSqlServer(builder.Configuration.GetConnectionString("Shop")));
builder.Services.AddScoped<IOrderService, OrderService>();

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddAuthentication().AddJwtBearer();   // binds Authentication:Schemes:Bearer
builder.Services.AddAuthorization();
builder.Services.AddControllers();
builder.Services.AddValidation();                      // .NET 10 Minimal API validation
builder.Services.AddOpenApi();                         // OpenAPI 3.1 document
builder.Services.AddHealthChecks()
    .AddDbContextCheck<ShopDbContext>();               // EF Core health check package

var app = builder.Build();                             // service collection is now read-only

// ---- 3. Middleware pipeline (order matters) -------------------------
app.UseExceptionHandler();                             // outermost: sees every exception below
if (!app.Environment.IsDevelopment())
{
    app.UseHsts();
}
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

// ---- 4. Endpoints ---------------------------------------------------
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();                                  // /openapi/v1.json
}
app.MapControllers();
app.MapHealthChecks("/healthz").AllowAnonymous();

var orders = app.MapGroup("/api/orders").RequireAuthorization();
orders.MapGet("/{id:int}", async Task<Results<Ok<OrderDto>, NotFound>> (
        int id, IOrderService svc, CancellationToken ct) =>
    await svc.FindAsync(id, ct) is { } order
        ? TypedResults.Ok(order)
        : TypedResults.NotFound());

// ---- 5. Run ---------------------------------------------------------
app.Run();

flowchart LR
  A["CreateBuilder - config, logging, DI, Kestrel"] --> B["builder.Services.Add... - register services"]
  B --> C["Build - container frozen"]
  C --> D["app.Use... - middleware in order"]
  D --> E["app.Map... - endpoints"]
  E --> F["app.Run - start host, listen"]
  F --> G["Request: middleware chain, then endpoint"]

Phase 1: what CreateBuilder gives you for free

WebApplication.CreateBuilder wraps the Generic Host and applies sensible defaults. Knowing them explains a lot of "magic":

The builder exposes Services, Configuration (a ConfigurationManager, so sources you add are visible immediately), Environment, Logging, Metrics, plus WebHost (Kestrel and URL settings) and Host (generic host hooks, e.g. a third-party DI container). Two lighter variants exist: CreateSlimBuilder for Native AOT (no HTTPS/HTTP/3 setup, no regex or alpha route constraints) and CreateEmptyBuilder when you want to opt into everything yourself.

Phase 2: registering services

The Add* calls only describe services (type, implementation, lifetime). Nothing is constructed yet, so registration order rarely matters. Two exceptions: when the same service type is registered twice, the last registration wins for single resolution (IEnumerable<T> gets all of them), and framework TryAdd* calls skip types that are already registered. Use builder.Environment and builder.Configuration to branch here. Never call builder.Services.BuildServiceProvider() to "get a service early". That creates a second container with duplicate singletons, and the ASP0000 analyzer warns about it.

Phase 3: Build() and what a WebApplication is

Build() creates the root IServiceProvider and locks the service collection. Adding a service afterwards throws InvalidOperationException. The returned WebApplication implements three roles at once:

• IHost: app.Services, app.Lifetime, app.Run()/RunAsync().
• IApplicationBuilder: app.Use... adds middleware.
• IEndpointRouteBuilder: app.Map... adds endpoints (minimal APIs, controllers, health checks, SignalR hubs, Razor Pages).

Startup work that needs scoped services, such as dev-time seeding, must create a scope (using var scope = app.Services.CreateScope();). Resolving a scoped service from the root provider fails in Development because of scope validation.

Phase 4: middleware vs endpoints, and the implicit parts

Middleware runs for every request, in registration order on the way in and reverse order on the way out. Endpoints run only when routing selects them. WebApplication adds several things automatically:

• The developer exception page first, in Development.
• UseRouting at the start if you didn't call it and endpoints exist.
• UseAuthentication/UseAuthorization after routing if the corresponding services are registered and you didn't call them.
• UseEndpoints at the very end.

Because endpoints execute at the end, the position of Map* calls relative to Use* calls does not matter. The order of Use* calls does. A good default order: exception handling, HSTS/HTTPS redirection, static assets, routing, CORS, authentication, authorization, rate limiting and your own middleware, then endpoints. Call UseRouting() explicitly when middleware must run before route matching (URL rewriting) or must sit between matching and authorization.

Phase 5: Run and graceful shutdown

app.Run() starts the host: hosted services start, Kestrel binds its endpoints, and IHostApplicationLifetime.ApplicationStarted fires. On SIGTERM or Ctrl+C, ApplicationStopping fires, Kestrel stops accepting new connections, in-flight requests get up to HostOptions.ShutdownTimeout (30 seconds by default) to finish, and hosted services are stopped. Watch out for a naming trap: app.Run() starts the app, but app.Run(context => ...) is the terminal middleware extension from IApplicationBuilder.

Endpoint routing: match early, execute late

Before ASP.NET Core 3.0, MVC did its own routing at the end of the pipeline, so authorization and CORS middleware could not know which action would run. Endpoint routing splits routing into two steps. Matching happens in UseRouting: the router compiles every registered route pattern into an efficient matcher and selects an Endpoint. Execution happens in the endpoint middleware at the end. Everything in between can inspect the selected endpoint:

flowchart LR
  DS["Endpoint sources: controllers, minimal APIs, Razor Pages, hubs"] -.-> UR
  REQ["GET /api/products/42"] --> UR["UseRouting - select endpoint"]
  UR -->|"endpoint set"| MW["CORS, AuthN, AuthZ, rate limiter read metadata"]
  MW --> EP["Endpoint middleware runs the handler"]
  UR -->|"no match"| NX["Next middleware, then 404"]

app.UseRouting();

app.Use(async (ctx, next) =>
{
    // null before UseRouting, or when no endpoint matched
    Endpoint? endpoint = ctx.GetEndpoint();
    if (endpoint?.Metadata.GetMetadata<RequiresAuditAttribute>() is not null)
    {
        ctx.Response.Headers["X-Audited"] = "true";
    }
    await next(ctx);
});

app.UseAuthorization();   // reads [Authorize] / RequireAuthorization() metadata of the matched endpoint

This is why [Authorize], [EnableCors], [EnableRateLimiting] and .RequireAuthorization() are all "just metadata". The middleware does the work, and endpoint routing tells it what applies. With WebApplication, UseRouting and UseEndpoints are added implicitly if you don't call them.

Conventional routing (MVC apps)

A conventional route is a URL template defined once, in Program.cs, that maps URL segments to the controller and action route values:

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

app.MapAreaControllerRoute(
    name: "admin",
    areaName: "Admin",
    pattern: "admin/{controller=Dashboard}/{action=Index}/{id?}");

// GET /Products/Details/5  ->  ProductsController.Details(int id = 5)
// GET /                    ->  HomeController.Index()

It works well for server-rendered MVC sites where URLs follow a uniform controller/action/id shape. The downside is that URLs are coupled to class and method names, and HTTP verbs are not part of the template, which makes it a poor fit for REST APIs.

Attribute routing (APIs)

Attribute routing puts the template next to the code. Controller-level and action-level templates are combined, [controller] and [action] are token-replaced, and verb attributes ([HttpGet], [HttpPost]...) both add a template and restrict the method. [ApiController] requires attribute routing.

[ApiController]
[Route("api/[controller]")]                                  // -> api/products
public sealed class ProductsController(IProductService products) : ControllerBase
{
    [HttpGet]                                                // GET api/products?page=2
    public Task<IReadOnlyList<ProductDto>> List(int page, CancellationToken ct) =>
        products.ListAsync(page, ct);

    [HttpGet("{id:int:min(1)}", Name = "GetProduct")]        // GET api/products/42
    public async Task<ActionResult<ProductDto>> Get(int id, CancellationToken ct)
    {
        var product = await products.FindAsync(id, ct);
        return product is null ? NotFound() : product;
    }

    [HttpGet("by-code/{code:alpha:length(3)}")]              // GET api/products/by-code/abc
    public async Task<ActionResult<ProductDto>> GetByCode(string code, CancellationToken ct)
    {
        var product = await products.FindByCodeAsync(code, ct);
        return product is null ? NotFound() : product;
    }

    [HttpGet("/api/catalog/featured")]                       // leading "/" ignores the controller prefix
    public Task<IReadOnlyList<ProductDto>> Featured(CancellationToken ct) =>
        products.FeaturedAsync(ct);
}

Actions are either conventionally routed or attribute routed. Any route attribute on the controller or action removes it from conventional routes. MapControllers() maps attribute-routed controllers. MapControllerRoute maps conventional routes and also picks up attribute-routed controllers.

Templates and constraints

Constraints exist to disambiguate routes, for example /products/42 (by id) vs /products/abc (by code). If you use them for validation, a bad id returns 404 with no explanation instead of a 400 problem response. Keep constraints coarse (int, guid) and validate business rules in the handler or with validation. Custom constraints implement IRouteConstraint and are registered via RouteOptions.ConstraintMap. Note that CreateSlimBuilder leaves out regex and alpha constraints to keep Native AOT apps small.

How a match is chosen

When several templates match a URL, routing uses precedence, not registration order:

• Templates with more segments are more specific.
• A literal segment beats a parameter, and a constrained parameter beats an unconstrained one.
• Catch-all parameters are the least specific.
• HTTP method metadata then filters candidates. If the path matches but the verb doesn't, you get 405 Method Not Allowed.

If two candidates still tie (for example {id} and {slug}, both unconstrained strings), routing throws AmbiguousMatchException at request time, which surfaces as a 500. Fix it with a literal segment or a constraint. Use the Order property only as a last resort.

Minimal APIs, groups and link generation

var orders = app.MapGroup("/api/v1/orders").WithTags("Orders").RequireAuthorization();

orders.MapGet("/{id:guid}", async (Guid id, IOrderService svc, CancellationToken ct) =>
        await svc.FindAsync(id, ct) is { } o ? Results.Ok(o) : Results.NotFound())
    .WithName("GetOrder");

orders.MapPost("/", async (CreateOrder cmd, IOrderService svc, LinkGenerator links,
                           HttpContext http, CancellationToken ct) =>
{
    OrderDto order = await svc.CreateAsync(cmd, ct);
    string? location = links.GetPathByName(http, "GetOrder", new { id = order.Id });
    return TypedResults.Created(location, order);   // 201 + Location header
});

Generate URLs from route names (LinkGenerator, Url.Action, CreatedAtAction) instead of concatenating strings. Then changing a template never breaks links.

ControllerBase vs Controller

Controllers are discovered by convention: public, non-abstract classes whose name ends in Controller or that inherit [Controller]. A new instance is created per request and its constructor dependencies are resolved from the request scope. That is why constructor injection of scoped services like DbContext is safe in controllers. An API controller that derives from Controller still works, but it pulls in view features it never uses and confuses readers.

What [ApiController] changes

• Attribute routing is required. Actions are not reachable through conventional routes.
• Automatic HTTP 400. A built-in filter (ModelStateInvalidFilter) checks ModelState.IsValid before your action runs and returns ValidationProblemDetails. The classic if (!ModelState.IsValid) return BadRequest(ModelState); is dead code.
• Binding source inference. Complex types registered in DI come from [FromServices]. Other complex types come from [FromBody]. IFormFile comes from [FromForm]. Parameters whose names appear in the route template come from [FromRoute]. Everything else comes from [FromQuery].
• Multipart inference. IFormFile parameters imply multipart/form-data.
• ProblemDetails for errors. Bodiless error results such as NotFound() (status 400 or higher) are turned into RFC 9457-style ProblemDetails responses with a traceId.

Each behavior can be switched off via ApiBehaviorOptions (SuppressModelStateInvalidFilter, SuppressInferBindingSourcesForParameters, SuppressMapClientErrors, DisableImplicitFromServicesParameters), and InvalidModelStateResponseFactory customizes the 400 body. Apply it once on a base class or with [assembly: ApiController] so you cannot forget it on a new controller.

The four return-type options

flowchart TD
  Q1{"Minimal API endpoint?"} -->|"yes"| R1["TypedResults with a Results union"]
  Q1 -->|"no, controller"| Q2{"Success path has a body?"}
  Q2 -->|"yes"| R2["ActionResult of T"]
  Q2 -->|"no"| R3["IActionResult"]
  Q2 -->|"always 200 body"| R4["Plain T or IAsyncEnumerable of T"]

ActionResult<T> works through two implicit conversions: from T (wrapped in an ObjectResult, 200) and from any ActionResult (NotFound(), Problem()...). C# does not allow user-defined conversions from interfaces, so return repo.GetAll(); typed as IEnumerable<T> fails to compile. Materialize it (.ToList()) or wrap it in Ok(...).

A realistic API controller

[ApiController]
[Route("api/orders")]
[Produces("application/json")]
public sealed class OrdersController(IOrderService orders) : ControllerBase
{
    [HttpGet("{id:int}")]
    [ProducesResponseType<OrderDto>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<ActionResult<OrderDto>> GetById(int id, CancellationToken ct)
    {
        var order = await orders.FindAsync(id, ct);
        return order is null ? NotFound() : order;          // T converts to ActionResult<T>
    }

    [HttpPost]
    [ProducesResponseType<OrderDto>(StatusCodes.Status201Created)]
    [ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
    [ProducesResponseType<ProblemDetails>(StatusCodes.Status409Conflict)]
    public async Task<ActionResult<OrderDto>> Create(CreateOrderRequest request, CancellationToken ct)
    {
        // No ModelState check: [ApiController] already returned 400 if binding/validation failed.
        if (await orders.ExistsAsync(request.ExternalRef, ct))
        {
            return Problem(
                statusCode: StatusCodes.Status409Conflict,
                title: "Duplicate order",
                detail: $"An order with reference '{request.ExternalRef}' already exists.");
        }

        if (!await orders.IsDeliverableAsync(request.PostalCode, ct))
        {
            ModelState.AddModelError(nameof(request.PostalCode), "We don't deliver to this area.");
            return ValidationProblem(ModelState);           // same shape as the automatic 400
        }

        OrderDto created = await orders.CreateAsync(request, ct);
        return CreatedAtAction(nameof(GetById), new { id = created.Id }, created);   // 201 + Location
    }

    [HttpDelete("{id:int}")]
    public async Task<IActionResult> Delete(int id, CancellationToken ct) =>
        await orders.DeleteAsync(id, ct) ? NoContent() : NotFound();

    // HttpResults in a controller: fine, but always JSON and no output formatters
    [HttpGet("{id:int}/summary")]
    public async Task<Results<Ok<OrderSummary>, NotFound>> Summary(int id, CancellationToken ct) =>
        await orders.SummaryAsync(id, ct) is { } s ? TypedResults.Ok(s) : TypedResults.NotFound();
}

Gotchas that show up in real code reviews

• The Async suffix. MVC trims Async from action names by default (MvcOptions.SuppressAsyncSuffixInActionNames = true). CreatedAtAction(nameof(GetByIdAsync), ...) therefore fails at run time with "No route matches the supplied values". Name actions without the suffix, use a route name, or change the option.
• Mixing BadRequest(ModelState) and the automatic 400. Clients see two different error shapes. Use ValidationProblem() and Problem() so every error is a problem-details document.
• Returning entities. Exposing EF entities leaks columns and creates serialization cycles. Return DTOs.
• Fat controllers. Keep actions thin: map HTTP to an application service and back. Business rules don't belong in the controller.

Where each value comes from

Without [ApiController], a complex parameter is bound by the complex-object binder, which looks through form fields, route data and query string by property name. The JSON body is not read unless you add [FromBody], a classic "my object is always empty" bug. With [ApiController], complex types not registered in DI are inferred as [FromBody], IFormFile as [FromForm], names that appear in the route template as [FromRoute], and everything else as [FromQuery].

How binding and validation fit together

flowchart LR
  REQ["HTTP request"] --> VP["Value providers: route, query, header, form"]
  REQ --> IF["Input formatter: JSON body"]
  VP --> MB["Model binders: string to typed values"]
  MB --> P["Action parameters"]
  IF --> P
  P --> V["Validation: attributes, IValidatableObject"]
  V --> MS{"ModelState valid?"}
  MS -->|"no"| BR["400 ValidationProblemDetails"]
  MS -->|"yes"| ACT["Action runs"]

Non-body sources go through value providers (key/value lookups) and model binders (string to int, Guid, DateOnly, collections, complex types). Conversion failures become ModelState errors such as "The value 'abc' is not valid for Id." The body goes through an input formatter. If the JSON is malformed, or a C# required member is missing, the formatter adds a model error and the request ends in a 400 as well. Validation then walks the bound object graph, including nested objects and collection items.

A realistic request model and action

using System.ComponentModel.DataAnnotations;

public sealed class CreateShipmentRequest : IValidatableObject
{
    [Required, StringLength(32, MinimumLength = 3)]
    public required string Reference { get; init; }          // 'required': JSON must contain it

    [Required, EmailAddress]
    public required string NotifyEmail { get; init; }

    [Range(0.01, 1000, ErrorMessage = "Weight must be between {1} and {2} kg.")]
    public decimal WeightKg { get; init; }

    [Required, MinLength(1)]
    public List<ShipmentLine> Lines { get; init; } = [];

    public DateOnly? PickupDate { get; init; }

    // Cross-property rules: runs only after the property-level attributes pass
    public IEnumerable<ValidationResult> Validate(ValidationContext context)
    {
        if (PickupDate is { } d && d < DateOnly.FromDateTime(DateTime.UtcNow))
            yield return new ValidationResult("Pickup date cannot be in the past.", [nameof(PickupDate)]);
    }
}

// For records, put validation attributes on the constructor parameters
public sealed record ShipmentLine([Required] string Sku, [Range(1, 999)] int Quantity);

[ApiController]
[Route("api/customers/{customerId:guid}/shipments")]
public sealed class ShipmentsController(IShipmentService shipments) : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<ShipmentDto>> Create(
        Guid customerId,                                                // inferred [FromRoute]
        CreateShipmentRequest request,                                  // inferred [FromBody]
        [FromQuery] bool dryRun,                                        // ?dryRun=true
        [FromHeader(Name = "Idempotency-Key")] string? idempotencyKey,
        CancellationToken ct)                                           // HttpContext.RequestAborted
    {
        // Reaching this line means binding and validation succeeded.
        ShipmentDto dto = await shipments.CreateAsync(customerId, request, dryRun, idempotencyKey, ct);
        return CreatedAtAction(nameof(Get), new { customerId, id = dto.Id }, dto);
    }

    [HttpGet("{id:int}")]
    public async Task<ActionResult<ShipmentDto>> Get(Guid customerId, int id, CancellationToken ct)
    {
        ShipmentDto? dto = await shipments.FindAsync(customerId, id, ct);
        return dto is null ? NotFound() : dto;
    }

    [HttpPost("{id:int}/label")]                                        // IFormFile: [FromForm] + multipart
    public async Task<IActionResult> UploadLabel(Guid customerId, int id, IFormFile file, CancellationToken ct)
    {
        await using Stream content = file.OpenReadStream();
        await shipments.SaveLabelAsync(customerId, id, content, ct);
        return NoContent();
    }
}

The same model works in a .NET 10 minimal API. Call builder.Services.AddValidation(), and a source generator discovers the parameter types, while an endpoint filter validates query, header and body values. Invalid input returns a 400 problem response automatically, and .DisableValidation() opts a single endpoint out:

builder.Services.AddValidation();

app.MapPost("/api/customers/{customerId:guid}/shipments",
    async (Guid customerId, CreateShipmentRequest request,
           [FromHeader(Name = "Idempotency-Key")] string? idempotencyKey,
           IShipmentService shipments, CancellationToken ct) =>
    {
        ShipmentDto dto = await shipments.CreateAsync(customerId, request, false, idempotencyKey, ct);
        return TypedResults.Created($"/api/customers/{customerId}/shipments/{dto.Id}", dto);
    });

Validation rules worth knowing

• Built-in attributes: [Required], [StringLength], [MinLength]/[MaxLength], [Range], [RegularExpression], [EmailAddress], [Phone], [Url], [Compare]. Write a custom ValidationAttribute for reusable single-value rules, and use IValidatableObject for rules that span several properties.
• Nullable reference types: with <Nullable>enable</Nullable>, MVC treats a non-nullable string property or parameter as if it had [Required(AllowEmptyStrings = true)]. Disable this with MvcOptions.SuppressImplicitRequiredAttributeForNonNullableReferenceTypes.
• Value types: [Required] on an int never fails, because a missing value is just 0. Use int? with [Required], the C# required modifier or [JsonRequired] for JSON, or [BindRequired] for route, query and form values.
• Parameters are validated too: [FromQuery, Range(1, 100)] int pageSize works on action parameters.
• MVC stops collecting errors after 200 by default (MaxModelValidationErrors).

DataAnnotations are for the shape of input. Business rules that need data, such as "is this reference unique?" or "is the item in stock?", belong in the application layer and map to 409 or 422 problem responses. FluentValidation is a popular alternative for complex rule sets. Its automatic MVC integration package is no longer recommended by the author, so call validators explicitly or from a filter.

How negotiation works in MVC

sequenceDiagram
  participant C as Client
  participant A as Controller action
  participant R as ObjectResult executor
  participant F as Output formatters
  C->>A: GET /api/products/42, Accept application/xml
  A->>R: return ProductDto
  R->>F: who can write ProductDto as application/xml?
  F-->>R: XmlSerializerOutputFormatter
  R-->>C: 200 OK, Content-Type application/xml

• Negotiation is implemented by ObjectResult: returning T, Ok(obj), CreatedAtAction(...), NotFound(obj), Problem(...). Format-specific results such as JsonResult, ContentResult and FileResult skip it.
• Media types in Accept are tried in quality (q) order. For each one, the formatters are asked whether they can write the type for that media type.
• No Accept header: the first registered formatter that can write the type is used (JSON).
• No formatter matches: by default ASP.NET Core quietly falls back to the first capable formatter. Set MvcOptions.ReturnHttpNotAcceptable = true to return 406 Not Acceptable instead.
• Browsers send Accept headers full of wildcards. If the header contains */*, it is ignored unless RespectBrowserAcceptHeader = true, so browsers get consistent JSON.
• Special cases: a string return is written as text/plain (StringOutputFormatter), and a null object becomes 204 No Content (HttpNoContentOutputFormatter). You can remove either formatter.
• [Produces("application/json")] pins the response format for an action or controller. [Consumes] restricts accepted request content types, and a body nobody can read yields 415 Unsupported Media Type.

Configuring and writing formatters

using System.Text.Json.Serialization;

builder.Services.AddControllers(options =>
    {
        options.RespectBrowserAcceptHeader = true;   // honor browser Accept headers (default: false)
        options.ReturnHttpNotAcceptable = true;      // 406 instead of silently falling back to JSON
        options.OutputFormatters.Add(new CsvOutputFormatter());
        options.FormatterMappings.SetMediaTypeMappingForFormat("csv", "text/csv");
    })
    .AddXmlSerializerFormatters()                    // application/xml input and output
    .AddJsonOptions(o =>
        o.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull);

using System.Globalization;
using System.Text;
using Microsoft.AspNetCore.Mvc.Formatters;
using Microsoft.Net.Http.Headers;

public sealed class CsvOutputFormatter : TextOutputFormatter
{
    public CsvOutputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/csv"));
        SupportedEncodings.Add(Encoding.UTF8);
    }

    protected override bool CanWriteType(Type? type) =>
        typeof(IEnumerable<ProductDto>).IsAssignableFrom(type);

    public override async Task WriteResponseBodyAsync(
        OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        var sb = new StringBuilder().AppendLine("Id,Name,Price");
        foreach (ProductDto p in (IEnumerable<ProductDto>)context.Object!)
        {
            sb.AppendLine(CultureInfo.InvariantCulture, $"{p.Id},{Escape(p.Name)},{p.Price}");
        }
        await context.HttpContext.Response.WriteAsync(sb.ToString(), selectedEncoding);
    }

    private static string Escape(string s) =>
        s.Contains(',') || s.Contains('"') ? $"\"{s.Replace("\"", "\"\"")}\"" : s;
}

[ApiController]
[Route("api/products")]
public sealed class ProductsController(IProductService products) : ControllerBase
{
    // Accept: application/json | application/xml | text/csv
    [HttpGet]
    public async Task<ActionResult<IReadOnlyList<ProductDto>>> List(CancellationToken ct) =>
        Ok(await products.ListAsync(ct));

    // URL-based format for clients that can't set headers: /api/products/42.xml
    [HttpGet("{id:int}.{format?}")]
    [FormatFilter]
    public async Task<ActionResult<ProductDto>> Get(int id, CancellationToken ct)
    {
        ProductDto? product = await products.FindAsync(id, ct);
        return product is null ? NotFound() : product;
    }
}

Formatters are tried in collection order, so Insert(0, ...) makes a formatter the preferred default. A custom formatter can resolve services through context.HttpContext.RequestServices, but not through its constructor, because formatters are created at startup.

Minimal APIs and HttpResults: no negotiation

Minimal API handlers and IResult types (Results, TypedResults) write the response themselves. They don't use MVC's formatters, so there is no content negotiation: objects are written as JSON, and the Content-Type is decided by the result type. If you need XML, CSV or vendor media types driven by Accept, either use controllers or inspect Accept yourself and return Results.Text(...) or Results.Stream(...) with an explicit content type.

Choosing status codes

Errors are content too. Return them as application/problem+json (ProblemDetails, RFC 9457) with a stable type, a human-readable title and a traceId. With AddProblemDetails(), [ApiController] and the exception handler, the framework already produces this shape for automatic 400s, bodiless 4xx results and unhandled exceptions. Your own Problem() calls should match it.

Environments: what they are and how they're set

IHostEnvironment.EnvironmentName is just a string, available as builder.Environment and app.Environment, with helpers IsDevelopment(), IsStaging(), IsProduction() and IsEnvironment("Testing"). It is read from:

• DOTNET_ENVIRONMENT or ASPNETCORE_ENVIRONMENT. With WebApplication, DOTNET_ENVIRONMENT takes precedence if both are set.
• The --environment command-line argument (e.g. dotnet Shop.Api.dll --environment Staging).
• Properties/launchSettings.json, used only by local tooling (dotnet run, Visual Studio, VS Code). Values there override machine environment variables, and the file plays no part in a deployed app.

If nothing is set, the app runs as Production. That is a safe default: no developer exception page, no user secrets, no scope validation. Containers and App Service are Production unless you say otherwise.

{
  "profiles": {
    "https": {
      "commandName": "Project",
      "applicationUrl": "https://localhost:7180;http://localhost:5180",
      "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" }
    }
  }
}

Providers and precedence

flowchart BT
  J["appsettings.json - committed defaults"] --> E["appsettings.Env.json - per-environment overrides"]
  E --> S["User secrets - Development only"]
  S --> V["Environment variables"]
  V --> CL["Command-line arguments"]
  CL --> X["Providers added in Program.cs - Key Vault, App Configuration"]
  X --> R["IConfiguration - last writer wins per key"]

Each provider contributes key/value pairs, and a key set by a later provider overrides the same key from an earlier one. Keys that are not overridden fall through, so you only override what differs. Underneath the app configuration sits host configuration: DOTNET_- and ASPNETCORE_-prefixed environment variables (prefix stripped) and the command line, read early to decide the environment, content root and URLs. Any provider you add after CreateBuilder is appended last and therefore beats even the command line. That is usually what you want for a vault, but it surprises people who expect command-line arguments to always win.

Keys, hierarchy and a worked example

JSON is flattened into Section:Sub:Key. Environment variables use a double underscore (Smtp__Port) because : isn't valid everywhere. Azure Key Vault secret names use --. Both are translated to :. Arrays become indexed keys (AllowedOrigins:0, AllowedOrigins:1). GetConnectionString("Shop") is shorthand for ConnectionStrings:Shop.

// appsettings.json (committed)
{
  "Smtp": { "Host": "localhost", "Port": 25, "UseTls": false },
  "FeatureFlags": { "NewCheckout": false }
}

// appsettings.Production.json (committed, no secrets)
{
  "Smtp": { "Host": "smtp.contoso.internal", "UseTls": true },
  "Logging": { "LogLevel": { "Default": "Warning" } }
}

# Container / Kubernetes environment
export ASPNETCORE_ENVIRONMENT=Production
export Smtp__Port=587
export ConnectionStrings__Shop="Server=sql-prod;Database=Shop;Authentication=Active Directory Default"

# Command-line arguments override everything CreateBuilder loaded
dotnet Shop.Api.dll --FeatureFlags:NewCheckout=true

JSON files are loaded with reloadOnChange: true, so edits are picked up at run time by IOptionsMonitor/IOptionsSnapshot. Environment variables and command-line values are fixed for the life of the process.

Secrets: development vs production

• Local development: the Secret Manager. dotnet user-secrets init adds a UserSecretsId to the project, and dotnet user-secrets set "ConnectionStrings:Shop" "..." writes to %APPDATA%\Microsoft\UserSecrets\<id>\secrets.json (~/.microsoft/usersecrets/<id>/secrets.json on Linux and macOS), outside the repository. It is not encrypted. It only keeps secrets out of git, and it is loaded only in Development.
• Production: a secret store. Use Azure Key Vault as a configuration provider, Azure App Configuration with Key Vault references, or Kubernetes secrets surfaced as environment variables or files (AddKeyPerFile). Better still, avoid secrets entirely with managed identities, as in the connection string above.

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    // Appended after the defaults: vault values override env vars and command line
    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVault:Name"]}.vault.azure.net/"),
        new DefaultAzureCredential());
}

builder.Services.AddOptions<SmtpOptions>()
    .BindConfiguration(SmtpOptions.Section)
    .ValidateDataAnnotations()
    .ValidateOnStart();                          // bad config fails the deployment, not the first email

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // Lists every key with the provider that supplied it. Never expose this outside Development.
    app.MapGet("/debug/config", (IConfiguration config) =>
        ((IConfigurationRoot)config).GetDebugView());
}

Keep environment-specific code to a minimum

Prefer configuration differences over if (env.IsProduction()) branches. Branches are fine for developer tooling (exception page, OpenAPI UI, debug endpoints) and for wiring providers such as Key Vault. Business behavior should depend on settings and feature flags, which you can change without a redeploy. Build one artifact (one container image) and promote it through environments by changing only configuration.

The options at a glance

Cookies

A cookie is the only state the browser sends back automatically, which makes it perfect for small identifiers and preferences and dangerous for anything you trust blindly. Always set the security flags explicitly:

app.MapPost("/preferences/theme/{theme}", (string theme, HttpResponse response) =>
{
    if (theme is not ("light" or "dark"))
        return Results.BadRequest();                 // cookies are user input: allow-list values

    response.Cookies.Append("theme", theme, new CookieOptions
    {
        HttpOnly = false,                            // the front end reads it; nothing sensitive inside
        Secure = true,                               // HTTPS only
        SameSite = SameSiteMode.Lax,                 // not sent on cross-site POSTs
        MaxAge = TimeSpan.FromDays(365),
        IsEssential = true                           // passes the cookie-consent check
    });
    return Results.NoContent();
});

If you must trust a cookie's content, encrypt and sign it with Data Protection (IDataProtector). This is what cookie authentication, session and TempData do. Otherwise store only an opaque ID and keep the data on the server. Remember that every cookie is sent on every request to its path, so large cookies cost bandwidth on each call.

Session: how it really works

sequenceDiagram
  participant B as Browser
  participant A as ASP.NET Core
  participant R as Redis cache
  B->>A: POST /checkout/shipping, no session cookie
  A->>R: save session data under a new key
  A-->>B: Set-Cookie .AspNetCore.Session with protected key
  B->>A: GET /checkout/payment with cookie
  A->>A: unprotect cookie with Data Protection
  A->>R: LoadAsync session data
  A-->>B: 200 page with draft data

var redis = ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis")!);

builder.Services.AddStackExchangeRedisCache(o =>
    o.ConnectionMultiplexerFactory = () => Task.FromResult<IConnectionMultiplexer>(redis));
builder.Services.AddDataProtection()
    .SetApplicationName("shop")
    .PersistKeysToStackExchangeRedis(redis, "DataProtection-Keys");   // every instance can decrypt
builder.Services.AddSession(o =>
{
    o.IdleTimeout = TimeSpan.FromMinutes(20);
    o.Cookie.HttpOnly = true;
    o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    o.Cookie.IsEssential = true;          // otherwise session is disabled until the user consents
});
builder.Services.AddControllersWithViews();

var app = builder.Build();
app.UseRouting();
app.UseSession();                         // after routing, before endpoints
app.MapDefaultControllerRoute();

public sealed class CheckoutController : Controller
{
    private const string DraftKey = "checkout:draft";

    [HttpPost, ValidateAntiForgeryToken]
    public async Task<IActionResult> Shipping(ShippingForm form)
    {
        if (!ModelState.IsValid) return View(form);

        await HttpContext.Session.LoadAsync();                    // avoid synchronous cache I/O
        CheckoutDraft draft = HttpContext.Session.GetString(DraftKey) is { } json
            ? JsonSerializer.Deserialize<CheckoutDraft>(json)!
            : new CheckoutDraft();
        HttpContext.Session.SetString(DraftKey, JsonSerializer.Serialize(draft with { Shipping = form }));

        TempData["Flash"] = "Shipping address saved.";             // lives until the next read
        return RedirectToAction(nameof(Payment));                  // Post/Redirect/Get
    }

    [HttpGet]
    public IActionResult Payment() => View();
}

Behaviors interviewers probe:

• Values are byte[]. There are helpers for string and int, and you serialize objects yourself (JSON).
• Session is non-locking. Two concurrent requests from the same browser each load the whole session, and the last one to commit wins.
• The idle timeout applies to the server-side data and is reset on each request. The cookie itself is a browser-session cookie. An empty session is not persisted, so the ID changes on every request until a value is set.
• Without LoadAsync(), the first access loads synchronously from the cache, which blocks a thread on network I/O.
• Session is not available in SignalR hubs or Blazor Server circuits, and it is ephemeral. The app must still work if it is lost.

TempData

TempData (MVC and Razor Pages only) keeps a value until it is read. Values are then deleted at the end of that request, unless you use Peek or Keep. This makes it the standard tool for Post/Redirect/Get flash messages. The default provider stores it in a Data-Protection-encrypted, chunked cookie, so keep it small. AddSessionStateTempDataProvider() switches it to session storage when the payload is larger. Like the session cookie, the TempData cookie is not marked essential by default.

Query strings, hidden fields, HttpContext.Items and cache

• Query strings are ideal for state that should be shareable and bookmarkable (filters, sort, page). They end up in logs, browser history and Referer headers, so never put tokens or personal data there.
• Hidden fields carry state across form posts, but the client controls them. Always revalidate on the server and never trust prices or IDs from them.
• HttpContext.Items is a per-request dictionary for passing data from middleware to endpoints, such as a resolved tenant. Prefer typed keys (a static object) to avoid collisions.
• Cache is shared state for performance. IMemoryCache is per instance, IDistributedCache is shared, and HybridCache (GA since .NET 9) combines both with stampede protection. Cached data must be recomputable from the source of truth.

One platform, four programming models

ASP.NET Core unified the old stacks, so there is no separate "Web API framework" any more. Controller derives from ControllerBase, Razor Pages reuse MVC's model binding, validation, filters and tag helpers, and Blazor components are routed through the same endpoint routing via MapRazorComponents<App>(). One application can host all of them. So the real questions are: what is the contract (HTML or JSON), who renders the UI (server or browser), and where does UI state live between interactions.

flowchart LR
  R["HTTP request"] --> M["Middleware: auth, routing"]
  M --> E{"Matched endpoint"}
  E -->|"Minimal API"| J["JSON response"]
  E -->|"API controller"| J
  E -->|"MVC controller"| V["Razor view to HTML"]
  E -->|"Razor Page"| PG["PageModel + cshtml to HTML"]
  E -->|"Razor component"| BC{"Render mode"}
  BC -->|"Static SSR"| H["HTML, no interactivity"]
  BC -->|"Interactive Server"| S["SignalR circuit on server"]
  BC -->|"Interactive WASM"| W[".NET in the browser"]

Web API: minimal APIs or controllers

Use a Web API when the consumer is code: a React or Angular SPA, a mobile app, a partner integration or another microservice. The webapi template generates minimal APIs by default (--use-controllers gives you controllers). Both styles produce the same endpoints and OpenAPI metadata; the difference is organization and features.

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;

// Minimal API: endpoints grouped per feature, typed results feed OpenAPI
public static class ProductEndpoints
{
    public static RouteGroupBuilder MapProducts(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/products").WithTags("Products");

        group.MapGet("/{id:int}", async Task<Results<Ok<Product>, NotFound>> (
            int id, IProductStore store, CancellationToken ct) =>
            await store.FindAsync(id, ct) is { } p ? TypedResults.Ok(p) : TypedResults.NotFound());

        group.MapPost("/", async (CreateProduct cmd, IProductStore store, CancellationToken ct) =>
        {
            var created = await store.AddAsync(cmd, ct);
            return TypedResults.Created($"/api/products/{created.Id}", created);
        });

        return group;
    }
}

// Controller: same endpoint, attribute routing + [ApiController] conventions
[ApiController]
[Route("api/[controller]")]
public sealed class ProductsController(IProductStore store) : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<ActionResult<Product>> Get(int id, CancellationToken ct)
        => await store.FindAsync(id, ct) is { } p ? Ok(p) : NotFound();
}

[ApiController] gives you automatic 400 ProblemDetails responses for invalid model state, binding-source inference and mandatory attribute routing, plus the full MVC filter pipeline. Minimal APIs have lower overhead, endpoint filters instead of MVC filters, built-in validation via builder.Services.AddValidation() since .NET 10, and they work with Native AOT through the Request Delegate Generator; MVC controllers do not support Native AOT. For a new service I default to minimal APIs organized by feature; for a large existing controller codebase or a team that depends on MVC filters and conventions, controllers are still a fine choice.

MVC vs Razor Pages: same engine, different organization

MVC routes a request to a controller action, which builds a model and returns View(); views live under Views/{Controller}/{Action}.cshtml. That fits apps where one controller coordinates many related screens or where routing is not page-shaped. Razor Pages make the page the unit: Pages/Products/Edit.cshtml plus its PageModel, routed by file path (/Products/Edit/5 with @page "{id:int}"). Handlers like OnGetAsync/OnPostAsync sit next to the markup, [BindProperty] binds the form, and antiforgery tokens are validated automatically. For a form-over-data site there is simply less ceremony.

// Pages/Products/Edit.cshtml.cs  (markup starts with: @page "{id:int}")
public sealed class EditModel(IProductStore store) : PageModel
{
    [BindProperty] public ProductInput Input { get; set; } = new();

    public async Task<IActionResult> OnGetAsync(int id, CancellationToken ct)
    {
        var product = await store.FindAsync(id, ct);
        if (product is null) return NotFound();
        Input = new ProductInput { Name = product.Name, Price = product.Price };
        return Page();
    }

    public async Task<IActionResult> OnPostAsync(int id, CancellationToken ct)
    {
        if (!ModelState.IsValid) return Page();       // redisplay with validation messages
        await store.UpdateAsync(id, Input.Name, Input.Price, ct);
        return RedirectToPage("Index");               // Post/Redirect/Get
    }
}

Blazor: components and render modes

A Blazor Web App (the unified template since .NET 8) renders components statically on the server by default and lets you opt into interactivity per page or component with a render mode. This is the part interviewers dig into, because the render mode decides where your code runs and what scales.

@page "/inventory"
@rendermode InteractiveServer
@inject IInventoryService Inventory

<h1>Stock levels</h1>
<button @onclick="RefreshAsync">Refresh</button>
<ul>
  @foreach (var item in items)
  {
    <li>@item.Sku: @item.Quantity</li>
  }
</ul>

@code {
    private IReadOnlyList<StockLevel> items = [];

    protected override async Task OnInitializedAsync() => items = await Inventory.GetAsync();

    private async Task RefreshAsync() => items = await Inventory.GetAsync();
}

With Interactive Server, every click travels to the server, the component re-renders there and only the DOM diff is sent back. .NET 10 adds circuit state persistence, so a user whose connection drops for a while can resume without losing unsaved work. With WebAssembly the component runs in the browser sandbox and must call a Web API for data, which is why Blazor WASM and Web API usually ship together.

Choosing: a decision table

Production concerns that decide it in practice

• Scaling: APIs, MVC and Razor Pages are stateless per request and scale horizontally behind any load balancer. Blazor Server is stateful: each circuit holds component state in server memory.
• Auth: server-rendered apps and Blazor Server use cookies naturally. SPAs and Blazor WASM need either a backend-for-frontend with cookies or tokens. Since .NET 10, cookie auth returns 401/403 for known API endpoints instead of redirecting to a login page.
• Testing: WebApplicationFactory<Program> covers all of them in integration tests; bUnit tests Blazor components in isolation.
• Team skills: a strong React team plus a .NET API is a perfectly valid answer; Blazor shines when the team is C#-first and wants shared models and validation.

What a DbContext really is

Think of the context as a unit of work. Every entity it loads is tracked in the change tracker with a state: Unchanged, Modified, Added, Deleted or Detached. SaveChangesAsync detects changes, orders the INSERT/UPDATE/DELETE statements and runs them in a single transaction. The tracker is also an identity map: within one context there is at most one instance per primary key, so two queries returning customer 7 give you the same object.

That design dictates the lifetime. A context should live for one unit of work, which in ASP.NET Core means one request: AddDbContext registers it as scoped. It is not thread-safe, so two concurrent queries on the same instance throw "A second operation was started on this context instance". For Blazor Server, background services or deliberate parallelism, inject IDbContextFactory<T> (AddDbContextFactory) and create one context per operation. AddDbContextPool reuses reset instances to save allocations in hot APIs.

public sealed class ShopDbContext(DbContextOptions<ShopDbContext> options) : DbContext(options)
{
    public DbSet<Customer> Customers => Set<Customer>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
        => modelBuilder.ApplyConfigurationsFromAssembly(typeof(ShopDbContext).Assembly);

    protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
    {
        // Pre-convention configuration: defaults for every property of a CLR type
        configurationBuilder.Properties<decimal>().HavePrecision(18, 2);
    }
}

// Program.cs
builder.Services.AddDbContext<ShopDbContext>(o =>
    o.UseSqlServer(builder.Configuration.GetConnectionString("Shop")));

app.MapPut("/customers/{id:int}/name", async (int id, RenameCustomer cmd, ShopDbContext db, CancellationToken ct) =>
{
    var customer = await db.Customers.FindAsync([id], ct);   // identity map first, then SQL
    if (customer is null) return Results.NotFound();

    customer.Name = cmd.Name;                                // tracker marks Name as Modified
    await db.SaveChangesAsync(ct);                           // UPDATE ... SET [Name] = @p0 WHERE [Id] = @p1
    return Results.NoContent();
});

DbSet<T>: the query root

DbSet<T> implements IQueryable<T>. LINQ operators only build an expression tree; nothing hits the database until you enumerate with ToListAsync, FirstOrDefaultAsync, CountAsync or await foreach. At that point the provider translates the tree to SQL. Write read endpoints as projections with AsNoTracking() so EF neither materializes full entities nor tracks them:

var orders = await db.Orders
    .AsNoTracking()
    .Where(o => o.CustomerId == id && o.Status != OrderStatus.Pending)
    .OrderByDescending(o => o.CreatedAt)
    .Select(o => new OrderListItem(o.Number, o.Total, o.CreatedAt))
    .ToListAsync(ct);

Exposing sets as => Set<T>() avoids nullable warnings and a pointless setter. Find/FindAsync is the one API that checks the identity map before going to the database.

Code-first vs database-first

dotnet ef dbcontext scaffold "Name=ConnectionStrings:Shop" Microsoft.EntityFrameworkCore.SqlServer \
  --output-dir Data/Entities --context-dir Data --context ShopDbContext \
  --no-onconfiguring --force

Name= reads the connection string from configuration, so no secret ends up in generated code, and --no-onconfiguring leaves registration to DI. Keep customizations in partial classes or customize the T4 templates, because --force regenerates everything. A common hybrid is to scaffold an existing database once, create a baseline migration, and continue code-first.

Conventions, annotations, Fluent API and who wins

Conventions cover most of the model without any configuration:

• A property named Id or <Type>Id is the primary key; integer and GUID keys are generated by the database or EF.
• The table name comes from the DbSet property, otherwise from the class name.
• With nullable reference types, string maps to NOT NULL and string? to NULL.
• On SQL Server, strings become nvarchar(max) unless you set a max length (key and index columns get nvarchar(450)).
• A navigation plus a <Navigation>Id property becomes a foreign key, and EF indexes it.
• Enums map to integers; decimal without explicit precision triggers a warning because values can be silently truncated.

flowchart LR
  A["Entity classes + DbSets"] --> B["Conventions"]
  B -->|"overridden by"| C["Data annotations"]
  C -->|"overridden by"| D["ConfigureConventions"]
  D -->|"overridden by"| E["Fluent API in OnModelCreating"]
  E --> F["Model built once, cached per context type"]
  F --> G["LINQ to SQL"]
  F --> H["Change tracking"]
  F --> I["Migrations"]

// Annotations: quick and visible, but they couple the entity to persistence (and UI validation)
[Index(nameof(Email), IsUnique = true)]
public class Customer
{
    public int Id { get; set; }
    [MaxLength(200)] public required string Name { get; set; }
    [MaxLength(320)] public required string Email { get; set; }
    public string? Phone { get; set; }
    public List<Order> Orders { get; } = [];
}

// Fluent API: everything annotations can do, plus much more
public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> b)
    {
        b.ToTable("Orders", "sales");
        b.Property(o => o.Number).HasMaxLength(32);
        b.HasIndex(o => o.Number).IsUnique();
        b.Property(o => o.Status).HasConversion<string>().HasMaxLength(20);
        b.Property(o => o.CreatedAt).HasDefaultValueSql("SYSUTCDATETIME()");
        b.HasQueryFilter("SoftDelete", o => !o.IsDeleted);          // EF 10 named filter
        b.HasOne(o => o.Customer).WithMany(c => c.Orders)
         .HasForeignKey(o => o.CustomerId)
         .OnDelete(DeleteBehavior.Restrict);
    }
}

My default is one IEntityTypeConfiguration<T> per entity, applied with ApplyConfigurationsFromAssembly. Entities stay clean, configuration is discoverable, and nothing important is split between two styles. Annotations are fine in small apps, but remember that [Required] and [MaxLength] also drive MVC and minimal API validation, which couples your API contract to your schema.

The vocabulary interviewers expect

• Principal / dependent: the principal owns the key being referenced; the dependent holds the FK column. "Where does the FK column live?" tells you which side is dependent.
• Reference navigation (Post.Blog) points to one entity; collection navigation (Blog.Posts) points to many. Navigations are optional; the FK is what defines the relationship in the database.
• Required vs optional: a non-nullable FK (int BlogId) means a post must have a blog; int? makes it optional.
• Shadow FK: if you only declare navigations, EF creates the FK as a shadow property you can reach via EF.Property<int>(post, "BlogId").

flowchart LR
  B["Blog"] -->|"1 to many"| P["Post"]
  P -->|"many to many"| T["Tag"]
  P -.->|"join table"| PT["PostTag"]
  T -.-> PT
  B -->|"1 to 0..1"| H["BlogHeader"]
  C["Customer"] -->|"complex type"| A["Address columns"]
  C -->|"owned, JSON"| PM["PaymentMethods column"]

One-to-many

The most common relationship, and usually fully discovered by convention: a collection navigation on one side, a reference navigation plus <Navigation>Id on the other. EF creates the FK constraint and an index on BlogId.

public class Blog
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public List<Post> Posts { get; } = [];          // collection navigation
    public BlogHeader? Header { get; set; }         // 1:1, optional
}

public class Post
{
    public int Id { get; set; }
    public required string Title { get; set; }
    public DateTime? PublishedOn { get; set; }
    public int BlogId { get; set; }                 // required FK
    public Blog Blog { get; set; } = null!;         // reference navigation
    public List<Tag> Tags { get; } = [];            // skip navigation (m:n)
}

// Only needed when names break convention or you change delete behavior
modelBuilder.Entity<Blog>()
    .HasMany(b => b.Posts)
    .WithOne(p => p.Blog)
    .HasForeignKey(p => p.BlogId)
    .OnDelete(DeleteBehavior.Cascade);

Defaults matter here. A required relationship gets ON DELETE CASCADE; an optional one gets ClientSetNull, meaning the database does nothing and EF nulls the FK only for dependents it is tracking. SQL Server refuses schemas with multiple cascade paths to the same table, so in real models you often switch one path to Restrict or NoAction and delete explicitly.

Many-to-many

Since EF Core 5 you can declare collections on both sides and EF creates a join table (here PostTag with a composite primary key) without a CLR class. Those are skip navigations: post.Tags.Add(tag) inserts a join row. When the join row needs data, such as when a tag was applied, make the join entity explicit:

public class Tag
{
    public int Id { get; set; }
    public required string Label { get; set; }
    public List<Post> Posts { get; } = [];
}

public class PostTag                               // explicit join entity with payload
{
    public int PostId { get; set; }
    public int TagId { get; set; }
    public DateTime TaggedAt { get; set; }
}

modelBuilder.Entity<Post>()
    .HasMany(p => p.Tags)
    .WithMany(t => t.Posts)
    .UsingEntity<PostTag>(
        j => j.Property(pt => pt.TaggedAt).HasDefaultValueSql("SYSUTCDATETIME()"));

PostId and TagId are picked up as FKs and as the composite key, and you keep the convenient skip navigations. If the join row grows real behavior (status, ordering, who added it), promote it to a first-class entity with two one-to-many relationships.

One-to-one

A one-to-one is a one-to-many with a unique index on the FK. Because both sides have reference navigations, EF cannot guess which one holds the FK, so you specify the dependent with the generic HasForeignKey<T>:

public class BlogHeader
{
    public int Id { get; set; }
    public string? Tagline { get; set; }
    public int BlogId { get; set; }                 // FK + unique index
    public Blog Blog { get; set; } = null!;
}

modelBuilder.Entity<Blog>()
    .HasOne(b => b.Header)
    .WithOne(h => h.Blog)
    .HasForeignKey<BlogHeader>(h => h.BlogId);

Ask whether it should be a separate table at all. If the data is always loaded with its owner and has no identity of its own, a complex type or table splitting is simpler.

Owned types and complex types

Owned types (OwnsOne, OwnsMany) were EF's original way to model DDD value objects such as an address: they live inside the owner's table, a separate table or a JSON column, and are always loaded with the owner. But owned types are still entity types with a hidden key, which causes surprises: you cannot assign the same instance to two properties, comparisons are by identity, and bulk updates are limited. Complex types (ComplexProperty, EF 8+) have true value semantics; EF 10 added optional complex types, JSON mapping and struct support, and the EF team now advises moving table-splitting and JSON mappings from owned types to complex types.

public sealed record Address
{
    public required string Street { get; init; }
    public required string City { get; init; }
    public required string PostalCode { get; init; }
}

modelBuilder.Entity<Customer>(b =>
{
    b.ComplexProperty(c => c.ShippingAddress);                // ShippingAddress_Street, _City ... columns
    b.ComplexProperty(c => c.BillingAddress, a => a.ToJson()); // EF 10: optional, one JSON column
    b.OwnsMany(c => c.PaymentMethods, pm => pm.ToJson());     // owned collection stored as JSON
});

Loading navigations

EF never loads navigations unless you ask, and it fixes up navigations between entities already tracked by the same context. Your options:

// Eager loading, with a filtered include and split queries to avoid cartesian explosion
var blogs = await db.Blogs
    .AsNoTracking()
    .Include(b => b.Posts.Where(p => p.PublishedOn != null))
        .ThenInclude(p => p.Tags)
    .AsSplitQuery()
    .ToListAsync(ct);

// Explicit loading of one navigation on an already tracked entity
var blog = await db.Blogs.SingleAsync(b => b.Id == id, ct);
await db.Entry(blog).Collection(b => b.Posts).LoadAsync(ct);

// Usually best for read endpoints: project exactly what you need
var summaries = await db.Blogs
    .Select(b => new BlogSummary(b.Id, b.Name, b.Posts.Count))
    .ToListAsync(ct);

Lazy loading (UseLazyLoadingProxies() with virtual navigations) exists, but it turns a loop over 50 blogs into 51 queries. I only enable it in desktop apps with small data sets, never in web APIs.

Setup: the design-time pieces

Migrations need two things: the dotnet-ef CLI tool and the Microsoft.EntityFrameworkCore.Design package in the startup project. The tool builds your project, starts it far enough to obtain a configured DbContext (through the host's DI container or an IDesignTimeDbContextFactory<T>), and then runs the migration operations.

# Pin the tool version with the repo (.NET 10 creates .config/dotnet-tools.json if missing)
dotnet tool install --local dotnet-ef
dotnet package add Microsoft.EntityFrameworkCore.Design --project src/Shop.Api

# Context lives in Infrastructure, configuration and DI live in the API project
dotnet ef migrations add AddCustomerEmail \
  --project src/Shop.Infrastructure --startup-project src/Shop.Api \
  --output-dir Persistence/Migrations

--project is where the migration files go (the assembly containing the context); --startup-project is the executable whose configuration and services are used. Mixing those two up is the most common "No DbContext was found" error.

What migrations add actually compares

Each add produces three things: the migration class (Up/Down), a .Designer.cs file holding the target model for that migration together with its [Migration("20261016093000_AddCustomerEmail")] ID, and an updated ShopDbContextModelSnapshot.cs. The snapshot is a C# description of the model as of the latest migration. EF builds today's model from your entities and configuration, diffs it against the snapshot, and emits operations such as AddColumn or CreateIndex.

flowchart LR
  M["Current model from OnModelCreating"] --> D{"Model differ"}
  S["ModelSnapshot.cs"] --> D
  D -->|"migrations add"| G["Migration Up, Down, Designer"]
  D --> S2["Snapshot rewritten"]
  G -->|"database update"| H{"Row in history table?"}
  H -->|"no"| X["Run Up, insert history row"]
  H -->|"yes"| K["Skip migration"]

Two consequences follow. First, generating a migration needs no database connection, so it works offline and in CI. Second, EF does not see drift: if someone altered the production schema by hand, the snapshot does not know, and the next migration may fail or conflict. The database's only record is __EFMigrationsHistory, which lists applied migration IDs and the EF product version.

The commands you use every week

Review and customize every migration

Generated migrations are a starting point, not a contract. Look at this one for a new required Email column with a unique index:

public partial class AddCustomerEmail : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.AddColumn<string>(
            name: "Email",
            table: "Customers",
            type: "nvarchar(320)",
            maxLength: 320,
            nullable: false,
            defaultValue: "");               // every existing row gets ''

        migrationBuilder.CreateIndex(
            name: "IX_Customers_Email",
            table: "Customers",
            column: "Email",
            unique: true);                   // fails as soon as two rows share ''
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropIndex(name: "IX_Customers_Email", table: "Customers");
        migrationBuilder.DropColumn(name: "Email", table: "Customers");
    }
}

It compiles and passes on an empty dev database, then breaks in production. The fix is to add the column as nullable, backfill with migrationBuilder.Sql(...), then make it required and add the index, possibly across two releases. Renames deserve the same care. A plain property rename is detected and scaffolded as RenameColumn, but rename the property and change its length or type in the same step and the differ can no longer match the columns: you get DropColumn plus AddColumn, data loss, and the warning "An operation was scaffolded that may result in the loss of data". Split the change or fix the migration by hand:

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.RenameColumn(name: "Name", table: "Customers", newName: "FullName");
    migrationBuilder.AlterColumn<string>(
        name: "FullName", table: "Customers", type: "nvarchar(200)",
        maxLength: 200, nullable: false,
        oldClrType: typeof(string), oldType: "nvarchar(max)");
    migrationBuilder.Sql("UPDATE Customers SET Email = LOWER(Email) WHERE Email IS NOT NULL;");
}

Applying migrations in production

• Idempotent SQL script, generated in CI, reviewed, and applied by the release pipeline. Best when DBAs want to see the SQL or when the app identity must not have DDL rights.
• Migration bundle (efbundle): a single executable that applies pending migrations given a --connection. No SDK or source code is needed on the deployment agent.
• Database.MigrateAsync() at startup: convenient for local development, demos and single-instance apps. In production it means several replicas racing (EF 9 added a migration lock, which prevents corruption but not slow, failing startups), the app needs schema-change permissions, and a failing migration becomes a failing deployment with no review step.

# CI gate: someone changed the model but forgot the migration
dotnet ef migrations has-pending-model-changes --project src/Shop.Infrastructure --startup-project src/Shop.Api

# Artifact for the release pipeline
dotnet ef migrations script --idempotent --output artifacts/migrate.sql \
  --project src/Shop.Infrastructure --startup-project src/Shop.Api

# Or a self-contained bundle
dotnet ef migrations bundle --self-contained -r linux-x64 --output artifacts/efbundle \
  --project src/Shop.Infrastructure --startup-project src/Shop.Api
./artifacts/efbundle --connection "$SHOP_DB"

Transactions changed recently: EF 9 applied all pending migrations in one transaction as part of migration locking, and EF 10 went back to wrapping each migration in its own transaction. Some operations, such as memory-optimized table changes, cannot run inside a transaction at all, so keep them in their own migration.

The provider model and which SqlClient to use

System.Data.Common defines abstract classes (DbConnection, DbCommand, DbParameter, DbDataReader, DbTransaction, DbProviderFactory), and each database ships a provider: Microsoft.Data.SqlClient, Npgsql, MySqlConnector, Microsoft.Data.Sqlite. Dapper is a set of extension methods over DbConnection; EF Core's relational providers build on the same classes.

For SQL Server, Microsoft.Data.SqlClient is the actively developed driver: Entra ID authentication, Always Encrypted improvements, TDS 8 strict encryption. System.Data.SqlClient was officially deprecated in 2024 and is not supported on .NET 9 and later. Migration is mostly a namespace swap, with one notable behavior change: since Microsoft.Data.SqlClient 4.0, Encrypt defaults to true, so servers with self-signed certificates fail with a trust error. Fix the certificate in production; use TrustServerCertificate=True only for local development.

flowchart TB
  A["Application code"] --> D["Dapper or EF Core"]
  A --> P["ADO.NET abstractions"]
  D --> P
  P --> S["Microsoft.Data.SqlClient"]
  S --> PL{"Pool per connection string"}
  PL -->|"reuse physical conn"| DB[("SQL Server")]

Connection, command, reader

The canonical read path: open a connection, create a command with typed parameters, stream rows with a reader, map them to objects.

using System.Data;
using Microsoft.Data.SqlClient;

public sealed record OrderRow(int Id, string Number, decimal Total, DateTime CreatedAt);

public sealed class OrderQueries(string connectionString)
{
    public async Task<List<OrderRow>> GetRecentAsync(int customerId, int take, CancellationToken ct)
    {
        const string sql = """
            SELECT TOP (@take) Id, Number, Total, CreatedAt
            FROM dbo.Orders
            WHERE CustomerId = @customerId
            ORDER BY CreatedAt DESC;
            """;

        await using var connection = new SqlConnection(connectionString);
        await connection.OpenAsync(ct);                         // borrowed from the pool

        await using var command = new SqlCommand(sql, connection);
        command.Parameters.Add("@customerId", SqlDbType.Int).Value = customerId;
        command.Parameters.Add("@take", SqlDbType.Int).Value = take;

        await using var reader = await command.ExecuteReaderAsync(ct);
        int id = reader.GetOrdinal("Id"), number = reader.GetOrdinal("Number"),
            total = reader.GetOrdinal("Total"), created = reader.GetOrdinal("CreatedAt");

        var rows = new List<OrderRow>();
        while (await reader.ReadAsync(ct))
        {
            rows.Add(new OrderRow(
                reader.GetInt32(id), reader.GetString(number),
                reader.GetDecimal(total), reader.GetDateTime(created)));
        }
        return rows;
    }                                                           // dispose returns the connection to the pool
}

The three execute methods map to three intents: ExecuteReaderAsync for result sets, ExecuteNonQueryAsync for INSERT/UPDATE/DELETE (returns rows affected), ExecuteScalarAsync for the first column of the first row. Multi-statement work uses a transaction that every command must be enlisted in:

await using var connection = new SqlConnection(connectionString);
await connection.OpenAsync(ct);
await using var tx = (SqlTransaction)await connection.BeginTransactionAsync(ct);
try
{
    await using var update = new SqlCommand(
        "UPDATE dbo.Orders SET Status = 'Cancelled' WHERE Id = @id AND Status = 'Pending';", connection, tx);
    update.Parameters.Add("@id", SqlDbType.Int).Value = orderId;
    var affected = await update.ExecuteNonQueryAsync(ct);

    await using var audit = new SqlCommand(
        "INSERT INTO dbo.OrderAudit (OrderId, Reason) VALUES (@id, @reason);", connection, tx);
    audit.Parameters.Add("@id", SqlDbType.Int).Value = orderId;
    audit.Parameters.Add("@reason", SqlDbType.NVarChar, 400).Value = (object?)reason ?? DBNull.Value;
    await audit.ExecuteNonQueryAsync(ct);

    await tx.CommitAsync(ct);
}
catch
{
    await tx.RollbackAsync(ct);
    throw;
}

Parameters: security, plan reuse and correct types

Parameters do three jobs. They prevent SQL injection because values are never parsed as SQL. They let SQL Server reuse one cached execution plan for every value. And they carry an exact type, which matters more than people expect. AddWithValue("@email", email) infers nvarchar with a length equal to the current string, so each distinct length produces a different plan in the cache, and comparing an nvarchar parameter to a varchar column forces an implicit conversion that can turn an index seek into a scan. Specify SqlDbType and size explicitly, pass DBNull.Value for nulls, and use a table-valued parameter (SqlDbType.Structured) or a JSON parameter with OPENJSON for lists. Table and column names cannot be parameters: validate them against an allow-list.

DataReader vs DataSet

using var connection = new SqlConnection(connectionString);
using var adapter = new SqlDataAdapter("SELECT Id, Name, Price FROM dbo.Products;", connection);
var table = new DataTable("Products");
adapter.Fill(table);   // opens and closes the connection if it was closed

For large binary or text columns, ExecuteReaderAsync(CommandBehavior.SequentialAccess, ct) lets you stream a column with GetStream instead of buffering the whole row.

Connection pooling

Opening a physical connection costs a TCP handshake, TLS and login, so SqlClient pools them. A pool exists per unique connection string per process; with integrated security the Windows identity is part of the key. Open takes an idle connection or creates one; Close/Dispose returns it, and its session state is reset on the next reuse. When all Max Pool Size connections are busy, Open waits up to Connect Timeout and then fails with "Timeout expired. The timeout period elapsed prior to obtaining a connection from the pool". By default unused connections above Min Pool Size are pruned after roughly four to eight minutes; Microsoft.Data.SqlClient 7.1 added an explicit Connection Idle Timeout.

Pool exhaustion is almost never fixed by raising Max Pool Size. The usual causes are leaked connections (no using), readers left open, connections held across slow HTTP calls, or thread-pool starvation from sync-over-async so connections are not returned in time. Measure with dotnet-counters monitor --counters Microsoft.Data.SqlClient.EventSource: number-of-active-connections, number-of-free-connections and number-of-reclaimed-connections (connections collected by the GC because nobody disposed them) tell the story.

What Identity gives you, and what it does not

Identity is a set of services over a pluggable store. UserManager<TUser> creates users, hashes and validates passwords, manages claims, roles, tokens and lockout. SignInManager<TUser> checks credentials, applies lockout and 2FA rules and issues the authentication cookie or token. IUserClaimsPrincipalFactory turns a user into a ClaimsPrincipal. The EF Core store maps it all to tables such as AspNetUsers, AspNetRoles, AspNetUserRoles, AspNetUserClaims, AspNetRoleClaims, AspNetUserLogins and AspNetUserTokens.

What it is not: a token server for other applications. It will not give you SSO between three apps, OIDC discovery, client credentials for machine-to-machine calls, or federation with a customer's Entra ID tenant on its own. For that you add an OIDC server or use an external provider.

flowchart LR
  U["Login page or API"] --> SM["SignInManager"]
  SM --> UM["UserManager"]
  UM --> PH["IPasswordHasher"]
  UM --> ST["IUserStore via EF Core"]
  ST --> DB[("AspNetUsers, Roles, Claims")]
  SM --> CF["Claims principal factory"]
  CF --> CK["Cookie or bearer token"]
  CK --> AZ["Authorization policies"]

There are several registration flavors: AddIdentity<TUser, TRole>() for cookie-based MVC or Razor Pages apps, AddDefaultIdentity<TUser>() to include the prebuilt Razor UI, AddIdentityCore<TUser>() for just the managers, and AddIdentityApiEndpoints<TUser>() with MapIdentityApi<TUser>() for SPA and mobile backends.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseSqlServer(builder.Configuration.GetConnectionString("App")));

builder.Services
    .AddIdentityApiEndpoints<AppUser>(o =>
    {
        o.Password.RequiredLength = 12;
        o.Lockout.MaxFailedAccessAttempts = 5;
        o.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15);
        o.User.RequireUniqueEmail = true;
        o.SignIn.RequireConfirmedEmail = true;
    })
    .AddRoles<IdentityRole>()
    .AddEntityFrameworkStores<AppDbContext>();

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("CanRefund", p => p.RequireClaim("permission", "orders.refund"))
    .AddPolicy("Support", p => p.RequireRole("Support", "Admin"));

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

app.MapGroup("/account").MapIdentityApi<AppUser>();   // /register, /login, /refresh, /manage/2fa ...
app.MapPost("/orders/{id:int}/refund", (int id) => TypedResults.Accepted($"/orders/{id}"))
   .RequireAuthorization("CanRefund");
app.Run();

public sealed class AppUser : IdentityUser
{
    public string? DisplayName { get; set; }
}

public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
    : IdentityDbContext<AppUser>(options);

Password hashing done properly

Identity never stores passwords, only a hash produced by PasswordHasher<TUser>. The current (v3) format is PBKDF2 with HMAC-SHA512, a random 128-bit salt per password, a 256-bit derived key and 100,000 iterations. The output is self-describing: a format marker, the PRF, the iteration count, the salt length, the salt and the subkey, base64-encoded into PasswordHash. Three consequences are worth saying out loud:

• Slow by design. The iteration count makes offline brute force expensive; the per-user salt defeats rainbow tables and hides identical passwords.
• Upgradable. Because parameters travel with the hash, you can raise PasswordHasherOptions.IterationCount at any time. Verification of an older hash returns PasswordVerificationResult.SuccessRehashNeeded, and Identity re-hashes on the next successful login. Older Identity versions used HMAC-SHA256 with far fewer iterations, and those hashes migrate the same way.
• Replaceable. Implement IPasswordHasher<TUser> to use Argon2id, or to verify a legacy system's hashes during a migration and return SuccessRehashNeeded.

builder.Services.Configure<PasswordHasherOptions>(o => o.IterationCount = 210_000);

Defaults you should know: the password policy requires 6 characters with digit, upper, lower and non-alphanumeric; lockout triggers after 5 failures for 5 minutes. Modern guidance favors longer passphrases plus a breached-password check over composition rules, which you can add with a custom IPasswordValidator<TUser>.

Roles, claims and policies

At sign-in, the claims principal factory loads the user's claims, roles and role claims into the principal; for cookie auth they are serialized into the encrypted cookie. Roles are just claims of type ClaimTypes.Role, which is why RequireRole works. Endpoints should depend on policies, not on role names scattered through code, so you can change who has a permission without touching endpoints.

The cached principal is why "I removed the role but the user still has access" happens. The cookie is re-validated against the user's security stamp every 30 minutes by default. When you change a user's roles or password, call UpdateSecurityStampAsync, and lower SecurityStampValidatorOptions.ValidationInterval if revocation must be faster.

Tokens, 2FA, external logins, passkeys

• Data Protection encrypts cookies and protects email confirmation and password reset tokens (one-day lifetime by default). The key ring must be persisted and shared across instances, otherwise every deploy or scale-out logs users out and invalidates reset links.
• Two-factor with authenticator apps (TOTP) and recovery codes is built in.
• External logins (Google, Microsoft, any OIDC provider) link to a local account through AspNetUserLogins.
• Passkeys (WebAuthn/FIDO2) are supported by Identity in .NET 10, and the Blazor Web App template includes passkey registration and login. They are phishing-resistant because the credential is bound to your origin.
• MapIdentityApi tokens are opaque, Data Protection-based bearer tokens, not JWTs. They suit your own SPA or mobile app; third-party clients need a real OIDC server. Since .NET 10, cookie authentication returns 401/403 instead of a login redirect for known API endpoints.

Identity vs an external identity provider

My rule of thumb: one application with its own user base and no SSO requirement, Identity is pragmatic and cheap. Several apps, APIs called by third parties, enterprise customers who want to sign in with their own directory, or strict compliance requirements: use an external provider and treat your app as a relying party. A middle path is Identity as the local account store with OpenIddict on top to issue standard tokens.

The three frameworks side by side

The lifecycle row matters most. xUnit's new-instance-per-test design makes shared mutable state across tests hard to write by accident. NUnit's shared fixture instance is convenient for expensive setup, but fields mutated in one test leak into the next unless [SetUp] resets them (or you opt into [FixtureLifeCycle(LifeCycle.InstancePerTestCase)]). In practice, choose what the team already uses; I default to xUnit for new code, and nobody should rewrite a healthy NUnit or MSTest suite.

Arrange-Act-Assert with sensible doubles

A good unit test reads like a specification: name the behavior, arrange only what matters, perform one action, assert on observable outcomes.

using Microsoft.Extensions.Time.Testing;
using NSubstitute;

public sealed class CheckoutServiceTests
{
    private readonly FakeTimeProvider _clock = new(new DateTimeOffset(2026, 11, 27, 9, 0, 0, TimeSpan.Zero));
    private readonly InMemoryOrderRepository _orders = new();                       // fake
    private readonly IPaymentGateway _payments = Substitute.For<IPaymentGateway>(); // stub or mock
    private readonly CheckoutService _sut;

    public CheckoutServiceTests() => _sut = new CheckoutService(_orders, _payments, _clock);

    [Fact]
    public async Task PlaceOrder_saves_order_when_payment_is_approved()
    {
        // Arrange
        var ct = TestContext.Current.CancellationToken;          // xUnit v3
        _payments.ChargeAsync(7, 120m, Arg.Any<CancellationToken>())
                 .Returns(PaymentResult.Success("tx-42"));        // stub: canned answer

        // Act
        var result = await _sut.PlaceOrderAsync(new Cart(CustomerId: 7, Total: 120m), ct);

        // Assert: state, not implementation details
        Assert.True(result.IsSuccess);
        var saved = Assert.Single(_orders.All);
        Assert.Equal(_clock.GetUtcNow(), saved.PlacedAt);
    }

    [Fact]
    public async Task PlaceOrder_does_not_save_when_payment_is_declined()
    {
        var ct = TestContext.Current.CancellationToken;
        _payments.ChargeAsync(default, default, default)
                 .ReturnsForAnyArgs(PaymentResult.Declined());

        var result = await _sut.PlaceOrderAsync(new Cart(7, 120m), ct);

        Assert.False(result.IsSuccess);
        Assert.Empty(_orders.All);
        await _payments.Received(1).ChargeAsync(7, 120m, Arg.Any<CancellationToken>()); // mock-style check
    }
}

Theories: one test, many cases

When the logic is the same and only data varies, use a theory instead of copy-pasted tests. Each data row is reported as its own test case, so a failure tells you exactly which input broke. TheoryData<...> is strongly typed and works for values that cannot be attribute arguments, such as decimal.

public sealed class ShippingCostTests
{
    public static TheoryData<decimal, string, decimal> Cases => new()
    {
        { 10m,    "NL", 4.95m },
        { 49.99m, "NL", 4.95m },   // boundary just below free shipping
        { 50m,    "NL", 0m },
        { 50m,    "US", 14.95m },
    };

    [Theory]
    [MemberData(nameof(Cases))]
    public void Calculates_shipping(decimal orderTotal, string country, decimal expected)
        => Assert.Equal(expected, ShippingCost.For(orderTotal, country));

    [Theory]
    [InlineData("NL")]
    [InlineData("US")]
    public void Rejects_zero_total(string country)
        => Assert.Throws<ArgumentOutOfRangeException>(() => ShippingCost.For(0m, country));
}

// NUnit equivalent:  [TestCase("NL")] public void Rejects_zero_total(string country) { ... }
// MSTest equivalent: [TestMethod] [DataRow("NL")] public void Rejects_zero_total(string country) { ... }

Test doubles: use the precise word

flowchart TD
  Q1{"Slow, I/O or nondeterministic?"} -->|"no"| R1["Use the real object"]
  Q1 -->|"yes"| Q2{"Asserting a call to it?"}
  Q2 -->|"yes, side effect"| M["Mock: verify the call"]
  Q2 -->|"no, it feeds data"| Q3{"Simple working version?"}
  Q3 -->|"yes"| F["Fake: in-memory implementation"]
  Q3 -->|"no"| S["Stub: canned answers"]

public sealed class InMemoryOrderRepository : IOrderRepository
{
    private readonly List<Order> _orders = [];
    public IReadOnlyList<Order> All => _orders;

    public Task AddAsync(Order order, CancellationToken ct)
    {
        _orders.Add(order);
        return Task.CompletedTask;
    }

    public Task<Order?> FindAsync(int id, CancellationToken ct)
        => Task.FromResult(_orders.Find(o => o.Id == id));
}

Prefer state verification (what was saved, what was returned) over interaction verification (which methods were called), and reserve mocks for true outgoing side effects: a payment charged, an email sent, a message published. Over-mocked tests break on every refactoring while still passing when behavior is wrong. Some boundaries deserve fakes or real infrastructure rather than mocks: inject TimeProvider instead of calling DateTime.UtcNow, use a stub HttpMessageHandler instead of mocking HttpClient, and test data access against SQLite or a Testcontainers database instead of mocking DbSet or relying on the EF InMemory provider, which has no relational behavior.

Running tests in the .NET 10 world

dotnet test historically drove VSTest. The newer Microsoft.Testing.Platform (MTP) runs test projects as normal executables, which makes them faster to start, easier to debug and Native AOT-capable. MSTest, NUnit and xUnit v3 all support it, and since the .NET 10 SDK dotnet test can run in MTP mode natively when global.json opts in:

{
  "sdk": { "version": "10.0.100", "rollForward": "latestFeature" },
  "test": { "runner": "Microsoft.Testing.Platform" }
}

A mixed solution should not combine VSTest and MTP projects, so migrate test projects together.

The everyday commands

dotnet --info                                   # SDKs, runtimes, this machine's RID
dotnet new list                                 # installed templates
dotnet new sln -n Shop                          # creates Shop.slnx with the .NET 10 SDK
dotnet new webapi -n Shop.Api -o src/Shop.Api
dotnet new xunit -n Shop.Api.Tests -o tests/Shop.Api.Tests
dotnet sln add src/Shop.Api tests/Shop.Api.Tests
dotnet reference add src/Shop.Api --project tests/Shop.Api.Tests       # noun-first form, .NET 10
dotnet package add Microsoft.EntityFrameworkCore.SqlServer --project src/Shop.Api

dotnet build -c Release                         # restore + compile into bin/Release/net10.0/
dotnet run --project src/Shop.Api -- --urls http://localhost:5080      # args after -- go to the app
dotnet watch --project src/Shop.Api             # rebuild / hot reload on file changes
dotnet test                                     # every test project in the solution
dotnet publish src/Shop.Api -c Release -o out   # -c Release is already the default for publish

Most commands restore implicitly; in CI you usually run dotnet restore once and then pass --no-restore (and --no-build to test and publish) to avoid repeated work. Pin the SDK with global.json so every machine and pipeline builds with the same version. The .NET 10 SDK also added noun-first aliases (dotnet package add, dotnet reference add), file-based apps (dotnet run app.cs with #:package directives), and native Microsoft.Testing.Platform support in dotnet test.

flowchart LR
  N["dotnet new"] --> P["csproj + sources"]
  P --> R["restore via NuGet"]
  R --> B["build: MSBuild + Roslyn"]
  B --> BIN["bin/Debug/net10.0"]
  BIN --> RUN["dotnet run"]
  BIN --> T["dotnet test"]
  R --> PUB["publish: Release, RID"]
  PUB --> OUT["publish folder or single file"]

build vs run vs publish

dotnet build output is meant for development: your assembly, a .deps.json describing dependencies, a .runtimeconfig.json naming the required framework, and copies of referenced assemblies. dotnet run builds and then starts that output through the app host; it needs the SDK and the source, so it does not belong on a production server. dotnet publish is the deployment step: it copies every dependency, selects RID-specific native assets, applies trimming, ReadyToRun or single-file if requested, and writes a folder you can copy, zip or put into a container image (dotnet publish -t:PublishContainer builds an image without a Dockerfile).

Framework-dependent vs self-contained

# Portable framework-dependent: runs anywhere with the .NET 10 runtime installed
dotnet publish src/Shop.Api -o out/fdd

# Framework-dependent but RID-specific: native apphost and native assets for linux-x64 only
dotnet publish src/Shop.Api -r linux-x64 -o out/fdd-linux

# Self-contained: bundles the runtime, nothing to install on the server
dotnet publish src/Shop.Api -r linux-x64 --self-contained -o out/scd

# Self-contained single file, trimmed and compressed (a CLI tool, for example)
dotnet publish src/Shop.Cli -r win-x64 --self-contained \
  -p:PublishSingleFile=true -p:PublishTrimmed=true -p:EnableCompressionInSingleFile=true

A framework-dependent app chooses its runtime from runtimeconfig.json: by default it runs on the latest installed patch of the requested major.minor version and only rolls forward to a higher minor version if the requested one is missing. The RollForward property (or DOTNET_ROLL_FORWARD) changes that policy.

Single-file

Single-file publish appends your managed assemblies to the native app host, producing one executable. Managed code is loaded straight from the bundle. Native libraries from NuGet packages stay next to the executable unless you set IncludeNativeLibrariesForSelfExtract, in which case they are extracted to a temporary directory on first run. It works for both framework-dependent and self-contained apps, and composes with trimming and ReadyToRun.

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <SelfContained>true</SelfContained>
  <PublishSingleFile>true</PublishSingleFile>
  <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
  <PublishReadyToRun>true</PublishReadyToRun>   <!-- optional: faster startup -->
</PropertyGroup>

Single-file is still IL running on the JIT. If you want a truly native binary with no JIT, that is Native AOT (PublishAot), which brings trimming and reflection constraints. Code that reads Assembly.Location gets an empty string in a single-file app; use AppContext.BaseDirectory. IIS in-process hosting cannot load single-file apps.

Runtime identifiers

A RID names the target platform as os-arch: win-x64, win-arm64, linux-x64, linux-arm64, linux-musl-x64 (Alpine and other musl-based distros), osx-arm64. The RID decides which native app host is generated, which runtimes/<rid>/native assets are copied from packages (SQLite, gRPC, image libraries), and which runtime pack is bundled for self-contained builds. Since .NET 8 the SDK uses a smaller RID graph of portable RIDs only, so distro-specific RIDs like ubuntu.22.04-x64 or win10-x64 are no longer recognized by default. --os and --arch are shortcuts that combine with the current machine's values.

The moving parts

• HTTP.sys receives requests in kernel mode; WAS activates and recycles worker processes; w3wp.exe runs the application pool.
• ANCM (AspNetCoreModuleV2) is registered as the handler for all paths of the site. It either hosts the runtime in-process or manages a child process.
• The Hosting Bundle installs the .NET runtime, the ASP.NET Core runtime and ANCM. Install it after IIS; if IIS is added later, repair the bundle.
• The application pool should be set to "No Managed Code", because ASP.NET Core does not use the .NET Framework CLR that this setting controls.

flowchart LR
  C["Client"] --> HS["HTTP.sys"]
  HS --> W1["w3wp.exe + ANCM"]
  W1 -->|"in-process"| IHS["IISHttpServer"]
  IHS --> P1["ASP.NET Core pipeline"]
  HS --> W2["w3wp.exe + ANCM"]
  W2 -->|"HTTP loopback"| K["Kestrel in app process"]
  K --> P2["ASP.NET Core pipeline"]

In-process hosting

ANCM loads CoreCLR into w3wp.exe, and the request goes from native IIS structures to managed code through IISHttpServer, an IServer implementation that replaces Kestrel. WebApplication.CreateBuilder calls UseIIS() for you, so the same app runs on Kestrel locally and in-process under IIS without code changes. Characteristics worth knowing:

• Highest throughput, since there is no second process and no proxying over loopback.
• One app per application pool. Two in-process apps in the same pool fail with 500.35 ANCM Multiple In-Process Applications in same Process.
• The pool's bitness must match the app and the installed runtime.
• Client disconnects cancel HttpContext.RequestAborted, and HttpRequest.Protocol reports HTTP/2 correctly.
• Process lifetime belongs to IIS: idle timeout, periodic recycling and on-demand start apply to your app, including its hosted services.

var builder = WebApplication.CreateBuilder(args);

// In-process server limits live here; IIS request filtering applies on top of them
builder.Services.Configure<IISServerOptions>(o =>
{
    o.MaxRequestBodySize = 50 * 1024 * 1024;
    o.AllowSynchronousIO = false;
});

Out-of-process hosting

Set <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel> in the project file (it becomes hostingModel="outofprocess" in web.config). ANCM now starts dotnet YourApp.dll or YourApp.exe on the first request, passes a random port in ASPNETCORE_PORT, waits up to startupTimeLimit (120 seconds by default) for Kestrel to listen, and forwards each request with forwarded headers and a pairing token that UseIISIntegration validates. If the process crashes, ANCM restarts it, up to rapidFailsPerMinute (10 by default). requestTimeout, 2 minutes by default, applies only to this model.

Choose it when you need several apps sharing a pool, want app crashes isolated from the worker process, depend on Kestrel-specific behavior, or deploy as a single-file app, which in-process hosting cannot load. Startup failures show up as 502.5 Process Failure.

web.config anatomy

IIS still needs a web.config, even though the app reads its own settings from appsettings.json. Publish generates one for web projects; customize it rather than deleting it.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\Shop.Api.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
        </environmentVariables>
        <handlerSettings>
          <handlerSetting name="enableShadowCopy" value="true" />
          <handlerSetting name="shadowCopyDirectory" value="../ShadowCopyDirectory/" />
        </handlerSettings>
      </aspNetCore>
      <security>
        <requestFiltering>
          <requestLimits maxAllowedContentLength="52428800" />
        </requestFiltering>
      </security>
    </system.webServer>
  </location>
</configuration>

• processPath/arguments: dotnet plus the DLL for framework-dependent apps, or .\Shop.Api.exe with no arguments for self-contained ones.
• stdoutLogEnabled: turn on only to diagnose startup failures; the folder must exist and be writable by the pool identity, and the logs are not rotated.
• environmentVariables: per-site overrides such as the environment name; keep secrets in a vault, not here.
• handlerSettings: shadow copying, plus debugFile/debugLevel for ANCM's own diagnostics log.
• requestLimits: IIS rejects bodies above maxAllowedContentLength before your app sees them, so raising only MaxRequestBodySize is not enough.

Deployment and troubleshooting

Running apps lock their DLLs. Dropping an app_offline.htm into the site root makes ANCM shut the app down gracefully (waiting up to shutdownTimeLimit, 10 seconds by default) and serve that page until you remove it; Web Deploy does this automatically. Shadow copying lets you overwrite files while the app runs, but IIS still recycles the app, so for zero downtime use two sites behind a load balancer or blue-green deployment.

Diagnose in this order: the Windows Application event log (ANCM writes there), run the app from a command prompt in the site folder to see the exception, then temporarily enable stdout or the ANCM debug log. Two more production settings: persist Data Protection keys (enable "Load User Profile" on the pool or configure a key store explicitly), and if the app runs background work, set the pool's start mode to AlwaysRunning with preload and Application Initialization, or the 20-minute idle timeout will shut it down.

The building blocks are just packages

Because they are host-agnostic, the same registration code works in an API, a worker, an Azure Functions isolated worker or a test. That is the point of the question: you should not need ASP.NET Core to write a well-structured background process.

What Host.CreateApplicationBuilder sets up

• Content root: the current directory (with a fallback to the app directory when started from C:\Windows\System32, as Windows services are).
• Environment: from DOTNET_ENVIRONMENT (web apps also read ASPNETCORE_ENVIRONMENT); Production if unset.
• Configuration, later sources overriding earlier ones: appsettings.json, appsettings.{Environment}.json, user secrets in Development, environment variables, command-line arguments. Import__BatchSize=1000 as an environment variable overrides Import:BatchSize.
• Logging: Console, Debug, EventSource and, on Windows, EventLog providers, filtered by the Logging section.
• DI validation in Development: scoped services resolved from the root and captive dependencies fail fast at build time.

A console app on the Generic Host

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddOptions<ImportOptions>()
    .BindConfiguration(ImportOptions.Section)
    .ValidateDataAnnotations()
    .ValidateOnStart();                              // fail at startup, not at 3 a.m.

builder.Services.AddHttpClient<CatalogClient>(c => c.BaseAddress = new Uri("https://catalog.internal/"))
    .AddStandardResilienceHandler();                 // Microsoft.Extensions.Http.Resilience
builder.Services.AddTransient<Importer>();

using var host = builder.Build();
await host.StartAsync();                             // runs ValidateOnStart and any hosted services

var lifetime = host.Services.GetRequiredService<IHostApplicationLifetime>();
await using (var scope = host.Services.CreateAsyncScope())
{
    var importer = scope.ServiceProvider.GetRequiredService<Importer>();
    await importer.RunAsync(lifetime.ApplicationStopping);   // Ctrl+C cancels the work
}

await host.StopAsync();

public sealed class ImportOptions
{
    public const string Section = "Import";
    [Required] public string SourceFolder { get; set; } = "";
    [Range(1, 10_000)] public int BatchSize { get; set; } = 500;
}

public sealed class Importer(CatalogClient catalog, IOptions<ImportOptions> options, ILogger<Importer> logger)
{
    public async Task RunAsync(CancellationToken ct)
    {
        var o = options.Value;
        logger.LogInformation("Importing from {Folder} in batches of {BatchSize}", o.SourceFolder, o.BatchSize);
        await catalog.PingAsync(ct);
        // ...
    }
}

Two details matter. ValidateOnStart runs inside StartAsync: if you resolve services from a host you never started, invalid options slip through until first use. And resolving a service from an explicit scope keeps scoped dependencies such as a DbContext correctly disposed.

Worker Service: long-running background work

The worker template uses Microsoft.NET.Sdk.Worker and registers a BackgroundService. The host calls StartAsync on each hosted service, BackgroundService launches ExecuteAsync and passes a stoppingToken that fires when the host shuts down.

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddWindowsService(o => o.ServiceName = "Shop Outbox Publisher"); // no-op unless run by the SCM
builder.Services.AddSystemd();                                                      // no-op unless run by systemd
builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddScoped<IOutboxBatch, SqlOutboxBatch>();
builder.Services.AddHostedService<OutboxPublisher>();
builder.Services.Configure<HostOptions>(o => o.ShutdownTimeout = TimeSpan.FromSeconds(45));
builder.Build().Run();

public sealed class OutboxPublisher(
    IServiceScopeFactory scopeFactory,
    TimeProvider time,
    ILogger<OutboxPublisher> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(5), time);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                // Hosted services are singletons: create a scope for scoped dependencies
                await using var scope = scopeFactory.CreateAsyncScope();
                var batch = scope.ServiceProvider.GetRequiredService<IOutboxBatch>();
                var sent = await batch.PublishPendingAsync(stoppingToken);
                if (sent > 0) logger.LogInformation("Published {Count} outbox messages", sent);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                logger.LogError(ex, "Outbox publishing failed; retrying on next tick");
            }
        }
    }
}

sequenceDiagram
  participant M as Main
  participant H as Host
  participant S as Hosted services
  participant L as Lifetime
  M->>H: Build then Run
  H->>S: StartingAsync, StartAsync, StartedAsync
  H->>L: ApplicationStarted
  Note over S: ExecuteAsync loops until cancelled
  L->>H: Ctrl+C or SIGTERM
  H->>L: ApplicationStopping
  H->>S: StopAsync in reverse order
  H->>L: ApplicationStopped

Behaviors worth knowing: an unhandled exception escaping ExecuteAsync stops the whole host by default (BackgroundServiceExceptionBehavior.StopHost, since .NET 6), which is why the loop catches and logs per iteration. Since .NET 10, all of ExecuteAsync runs as a background task, so synchronous code before the first await no longer delays the startup of other services. Graceful shutdown waits up to HostOptions.ShutdownTimeout, 30 seconds by default; keep it below your orchestrator's kill deadline. IHostedLifecycleService (.NET 8) adds Starting/Started/Stopping/Stopped hooks for ordering concerns such as warming caches before traffic.

Without a host at all

You can compose the pieces by hand for small tools or test harnesses:

IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables()
    .Build();

var services = new ServiceCollection();
services.AddSingleton(config);
services.AddLogging(b => b.AddConfiguration(config.GetSection("Logging")).AddConsole());
services.AddOptions<ImportOptions>().Bind(config.GetSection(ImportOptions.Section));
services.AddHttpClient<CatalogClient>();
services.AddTransient<Importer>();

await using var provider = services.BuildServiceProvider(new ServiceProviderOptions
{
    ValidateScopes = true,
    ValidateOnBuild = true
});

It works, but you re-implement what the host gives for free: environment-specific files, user secrets, command-line overrides, Ctrl+C and SIGTERM handling, hosted services and flushing logs on exit. For anything that runs unattended, use the host.

Stage 1: Roslyn produces IL and metadata

The C# compiler (Roslyn) parses, binds and lowers your code. Language features like async/await, iterators, lambdas, records, pattern matching and C# 14 extension members are all "lowered" into ordinary classes, state machines and method calls before emission. The output is an assembly (.dll) containing:

• IL (Intermediate Language): a stack-based, CPU-agnostic instruction set.
• Metadata: type definitions, member signatures, references, attributes. This is what reflection reads.
• A manifest and optional resources. Source generators and analyzers also run inside Roslyn at this stage, which is why they can replace reflection at runtime.

Roslyn performs very few optimizations. Even in Release builds it mainly removes nops and simplifies branches. The heavy optimization work belongs to the JIT, which knows the actual CPU, the actual loaded types and, with PGO, the actual runtime behavior.

# Inspect IL: open bin/Release/net10.0/MyApp.dll in ILSpy or sharplab.io
dotnet build -c Release

# See what the JIT generated (.NET 7+)
DOTNET_JitDisasm="OrderService:CalculateTotal" dotnet run -c Release

Stage 2: the CLR loads types and the JIT compiles on demand

When the host (dotnet or the app host executable) starts, the CLR loads the assembly, builds runtime type structures (method tables) and points each method at a stub. On the first call, the stub invokes the JIT, which verifies and compiles the IL to machine code, then patches the call target so later calls go straight to native code. This is why the first request to an API is slower than the second: you are paying for JIT, type loading and static constructors.

Stage 3: tiered compilation and Dynamic PGO

Optimized compilation is expensive, and most methods run only a few times. Tiered compilation (on by default since .NET Core 3.0) splits the work:

• Tier0: quick JIT with almost no optimizations, so startup is fast.
• Call counting: after a method is called roughly 30 times, it is queued for background re-JIT. With Dynamic PGO (on by default since .NET 8) hot methods first pass through an instrumented tier that records which types and branches actually occur.
• Tier1: fully optimized code that uses the profile: guarded devirtualization (for example "this IRepository is almost always SqlRepository"), hot/cold block layout, and better inlining decisions.
• OSR (On-Stack Replacement): a method stuck in a long-running loop at Tier0 can be switched to optimized code in the middle of the loop. This is why methods with loops no longer have to skip Tier0.

flowchart LR
  A["C# source"] -->|"Roslyn"| B["IL + metadata .dll"]
  B --> C{"Deployment model"}
  C -->|"JIT default"| D["Tier0 quick JIT + instrumentation"]
  D -->|"hot method ~30 calls or OSR"| E["Tier1 optimized with PGO"]
  C -->|"ReadyToRun"| F["Precompiled R2R code"]
  F -->|"hot method"| E
  C -->|"Native AOT"| G["ILCompiler whole-program"]
  G --> H["Single native executable, no JIT"]

ReadyToRun: precompiled but still managed

<PublishReadyToRun>true</PublishReadyToRun> runs crossgen2 at publish time and stores native code next to the IL in the same assembly. At startup the runtime uses that code instead of JIT-compiling, which can cut startup time considerably for large apps. Important properties:

• R2R code is roughly Tier0-plus quality and version-resilient, so hot methods are still re-JITted to Tier1 with PGO. You keep steady-state performance.
• Assemblies get bigger (IL plus native code) and are RID-specific (linux-x64, win-x64...).
• Reflection, Reflection.Emit, dynamic assembly loading all still work. It is a pure startup optimization with no compatibility cost.

Native AOT: no JIT at all

<PublishAot>true</PublishAot> uses ILCompiler to do whole-program analysis, trim unreachable code and emit a single native executable with a slim runtime (GC, type system, exception handling) linked in. Benefits are startup in tens of milliseconds, lower memory and small container images. The costs: no runtime code generation, reflection limited to what the compiler can see statically, trimming warnings you must fix, and no Dynamic PGO, so peak throughput can be slightly below a warmed-up JIT app.

Production knobs worth knowing

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <!-- Startup: precompile, still JIT hot paths later -->
  <PublishReadyToRun>true</PublishReadyToRun>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
  <!-- Defaults you rarely change: TieredCompilation, TieredPGO = true -->
  <!-- <TieredPGO>false</TieredPGO> to rule PGO out while investigating -->
</PropertyGroup>

For benchmarks, always let methods reach Tier1: BenchmarkDotNet handles warm-up for you, while a hand-rolled Stopwatch loop often measures Tier0 code and reaches the wrong conclusion.

How allocation works

Each thread gets an allocation context: a small chunk of gen0 memory where allocation is a pointer bump, which is why new in .NET is extremely fast. When the chunk is used up the thread asks the GC for another one. When the total gen0 allocation budget is exhausted, a GC is triggered. So in practice, the rate of allocation drives the rate of GCs: allocating less means fewer collections.

Generations and the generational hypothesis

• Gen0: freshly allocated objects. Collected very often and very cheaply because only live objects are touched, and most are already dead (request DTOs, LINQ iterators, strings built for one log line).
• Gen1: a buffer between short- and long-lived objects. Survivors of a gen0 GC land here.
• Gen2: long-lived data: caches, singletons, static data, pooled buffers. A gen2 (full) GC examines the entire heap and is the expensive one.

Collecting gen0 must not scan gen2, yet gen2 objects can point to gen0 objects. The runtime handles this with write barriers and a card table: every reference store into an older object marks a "card" so the GC only scans those dirty cards as extra roots. Practical consequence: a large, frequently mutated gen2 object graph (for example a giant cache dictionary that is constantly updated) makes even gen0 GCs slower.

flowchart LR
  A["new object below 85 KB"] --> G0["Gen0"]
  G0 -->|"survives GC"| G1["Gen1"]
  G1 -->|"survives GC"| G2["Gen2"]
  B["new object 85,000 bytes or more"] --> LOH["LOH, logically gen2"]
  C["GC.AllocateArray pinned: true"] --> POH["POH, never moved"]
  G0 -->|"dies young, most objects"| X["Reclaimed"]

LOH and POH

Objects of 85,000 bytes or more (configurable via GCLOHThreshold) go straight to the Large Object Heap. Copying them is expensive, so the LOH is swept rather than compacted by default and is only collected during gen2 GCs. Two consequences:

• Allocating many short-lived large arrays (for example reading each upload into a byte[], or building big JSON strings) causes gen2 GCs, the most expensive kind.
• The LOH can fragment. You can request a one-off compaction with GCSettings.LargeObjectHeapCompactionMode = GCLargeObjectHeapCompactionMode.CompactOnce, but the real fix is to avoid the allocations, typically with ArrayPool<T>.Shared, streaming, or RecyclableMemoryStream.

The Pinned Object Heap (.NET 5+) exists because pinning objects in gen0 blocks compaction and fragments the heap. Buffers that must stay at a fixed address (socket I/O, native interop) can be allocated directly on the POH with GC.AllocateArray<byte>(size, pinned: true) or GC.AllocateUninitializedArray. Kestrel and the networking stack use it for their memory pools.

// Rent instead of allocating large temporary buffers (avoids LOH churn)
byte[] buffer = ArrayPool<byte>.Shared.Rent(256 * 1024);
try
{
    int read = await stream.ReadAsync(buffer.AsMemory(0, buffer.Length), ct);
    Process(buffer.AsSpan(0, read));
}
finally
{
    ArrayPool<byte>.Shared.Return(buffer);
}

// Long-lived buffer passed to native code: allocate on the POH, no GCHandle pinning
byte[] ioBuffer = GC.AllocateArray<byte>(64 * 1024, pinned: true);

Regions (.NET 7+)

Historically each heap had fixed "segments" with gen0/gen1 living at the end of an ephemeral segment. Since .NET 7, on 64-bit, the GC manages memory as many smaller regions (small regions for SOH, larger ones for LOH). A generation is just a list of regions, so the GC can promote a whole region by relabeling it, hand free regions to whichever generation or heap needs them, and return memory to the OS more easily. You rarely configure regions directly, but they are why modern .NET is better at decommitting memory and why features like DATAS (dynamic heap count) are practical.

What triggers a GC, and what a GC does

A collection then: suspends managed threads (except during background gen2 marking), marks live objects from roots (stack slots, statics, GC handles, finalization queue, cards from older generations), plans whether to compact or sweep, relocates survivors and updates references, then resumes threads. Objects with finalizers survive one extra GC because they must first be put on the finalization queue, which is another reason to implement IDisposable correctly and call GC.SuppressFinalize.

Observing it in production

dotnet-counters monitor -n MyApi --counters System.Runtime
# Watch: dotnet.gc.collections (by generation), dotnet.gc.heap.total_allocated,
# dotnet.gc.last_collection.heap.size (gen0/gen1/gen2/loh/poh), dotnet.gc.pause.time

Healthy services show many gen0 GCs, fewer gen1, and rare gen2. A high gen2 rate usually means LOH churn or a mid-life crisis: objects living just long enough to be promoted (for example per-request objects held by a slow async call or a short-lived cache) and then dying in gen2.

Hypotheses: typical symptoms of wrong ordering

The mental model

flowchart LR
  A["Request"] --> FH["ForwardedHeaders"]
  FH --> EX["ExceptionHandler"]
  EX --> HS["HSTS / HttpsRedirection"]
  HS --> SF["Static files"]
  SF --> RT["Routing"]
  RT --> CO["CORS"]
  CO --> AN["Authentication"]
  AN --> AZ["Authorization"]
  AZ --> RL["Rate limiter / output cache"]
  RL --> CU["Custom middleware"]
  CU --> EP["Endpoint"]

Each middleware wraps the rest of the pipeline like a Russian doll. That is why the exception handler must be outermost: it wraps next() in a try/catch, and it can only catch what runs inside it. Response-modifying middleware (compression, headers) must also be outside the code producing the response, and must not modify headers after the response has started.

A correct Program.cs for an API

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddCors(o => o.AddPolicy("spa", p => p
    .WithOrigins("https://app.contoso.com")
    .AllowAnyHeader().AllowAnyMethod().AllowCredentials()));
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
builder.Services.AddRateLimiter(o => { /* policies */ });

var app = builder.Build();

app.UseForwardedHeaders();          // 1. fix scheme/IP from the proxy first
app.UseExceptionHandler();          // 2. outermost catch-all
if (!app.Environment.IsDevelopment()) app.UseHsts();
app.UseHttpsRedirection();
app.UseRouting();                   // explicit so the following can see the endpoint
app.UseCors("spa");                 // 3. before auth so preflight isn't 401
app.UseAuthentication();            // 4. who are you
app.UseAuthorization();             // 5. are you allowed
app.UseRateLimiter();               // 6. after routing for endpoint policies
app.UseMiddleware<CorrelationIdMiddleware>();

app.MapGroup("/api/orders").MapOrders().RequireAuthorization();
app.Run();

With WebApplication, if you do not call UseRouting yourself it is added at the start of the pipeline automatically, and endpoints execute at the end. Calling it explicitly makes the order visible and avoids surprises when you add middleware that must run before routing.

Writing custom middleware

Convention-based middleware is created once (singleton-like). Inject singletons in the constructor and scoped services as InvokeAsync parameters:

public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<CorrelationIdMiddleware> logger)
{
    private const string Header = "X-Correlation-Id";

    public async Task InvokeAsync(HttpContext context, ITenantContext tenant) // scoped: method injection
    {
        var id = context.Request.Headers[Header].FirstOrDefault() ?? Guid.CreateVersion7().ToString();
        context.TraceIdentifier = id;

        context.Response.OnStarting(() =>
        {
            context.Response.Headers[Header] = id;   // set before headers are flushed
            return Task.CompletedTask;
        });

        using (logger.BeginScope(new Dictionary<string, object> { ["CorrelationId"] = id, ["Tenant"] = tenant.Id }))
        {
            await next(context);                      // always pass the context along
        }
    }
}

Factory-based middleware implements IMiddleware, is resolved from DI per request (register it with the lifetime you want), and can take scoped services via the constructor:

public sealed class TenantResolutionMiddleware(TenantDbContext db) : IMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        var host = context.Request.Host.Host;
        if (!await db.Tenants.AnyAsync(t => t.Host == host, context.RequestAborted))
        {
            context.Response.StatusCode = StatusCodes.Status404NotFound;  // short-circuit
            return;
        }
        await next(context);
    }
}

builder.Services.AddScoped<TenantResolutionMiddleware>();
app.UseMiddleware<TenantResolutionMiddleware>();

Rules of thumb

• Never write to the response after calling next if the response may have started; check context.Response.HasStarted or use OnStarting.
• Do not capture scoped services in convention middleware constructors: that creates a captive dependency.
• Use app.UseWhen/MapWhen to branch the pipeline instead of if checks scattered across middleware.
• Prefer endpoint metadata (RequireAuthorization, RequireCors, RequireRateLimiting) over path checks inside middleware.

Where each one runs

flowchart TD
  A["HTTP request"] --> M["Middleware pipeline"]
  M --> R["Routing selects endpoint"]
  R --> E{"Endpoint type"}
  E -->|"Controller action"| AF["Authorization filters"]
  AF --> RF["Resource filters"]
  RF --> MB["Model binding + validation"]
  MB --> ACF["Action filters"]
  ACF --> ACT["Action method"]
  ACT --> RSF["Result filters"]
  RSF --> RES["Result execution"]
  E -->|"Minimal API"| EF["Endpoint filters"]
  EF --> H["Route handler"]

MVC exception filters handle exceptions thrown during controller creation, model binding, action filters and the action itself, but not exceptions from resource filters, result filters or result execution, and never from middleware. That is why the global error strategy should be middleware-based (UseExceptionHandler + IExceptionHandler), with filters only for endpoint-specific translation.

MVC filter types

Filters can be global (options.Filters.Add), per controller or per action via attributes. Use [ServiceFilter(typeof(T))] or [TypeFilter(typeof(T))] to get DI-constructed filters; plain attribute filters are instantiated by the framework and cannot take constructor dependencies. Ordering within a stage follows scope (global → controller → action) and IOrderedFilter.Order.

public sealed class AuditActionFilter(IAuditLog audit) : IAsyncActionFilter
{
    public async Task OnActionExecutionAsync(ActionExecutingContext ctx, ActionExecutionDelegate next)
    {
        var executed = await next();                 // runs the action (and inner filters)
        if (executed.Exception is null && ctx.HttpContext.Request.Method != HttpMethods.Get)
        {
            await audit.WriteAsync(
                ctx.ActionDescriptor.DisplayName!,
                ctx.HttpContext.User.Identity?.Name,
                ctx.ActionArguments);
        }
    }
}

builder.Services.AddScoped<AuditActionFilter>();
builder.Services.AddControllers(o => o.Filters.AddService<AuditActionFilter>());

Endpoint filters for Minimal APIs

Minimal APIs do not have the MVC filter pipeline. Instead, IEndpointFilter wraps the handler, with access to the bound arguments through EndpointFilterInvocationContext and to whatever the handler returns:

public sealed class IdempotencyFilter(IIdempotencyStore store) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var key = ctx.HttpContext.Request.Headers["Idempotency-Key"].ToString();
        if (string.IsNullOrEmpty(key))
            return TypedResults.Problem("Idempotency-Key header is required", statusCode: 400);

        if (await store.TryGetAsync(key, ctx.HttpContext.RequestAborted) is { } cached)
            return cached;                                  // short-circuit

        var result = await next(ctx);                       // run handler (and inner filters)
        await store.SaveAsync(key, result, ctx.HttpContext.RequestAborted);
        return result;
    }
}

var orders = app.MapGroup("/api/orders").AddEndpointFilter<IdempotencyFilter>();
orders.MapPost("/", async (CreateOrder cmd, IOrderService svc, CancellationToken ct) =>
    TypedResults.Created($"/api/orders/{(await svc.CreateAsync(cmd, ct)).Id}"));

Filters registered on a group apply to every endpoint in it; multiple filters run in registration order on the way in, reverse on the way out. AddEndpointFilterFactory lets you inspect the handler's MethodInfo once at startup and return a no-op when the filter does not apply, avoiding per-request reflection. .NET 10's built-in validation (AddValidation) is itself implemented as an endpoint filter.

Choosing between them

The three lifetimes and what they mean in practice

The container owns disposal: anything it created that implements IDisposable/IAsyncDisposable is disposed when its scope (or the root, for singletons) is disposed. Instances you pass in yourself (AddSingleton(new Foo())) are not disposed by the container.

Captive dependencies

flowchart LR
  S["PricingService singleton"] -->|"captures at first resolve"| D["AppDbContext scoped"]
  R1["Request 1"] --> S
  R2["Request 2"] --> S
  R3["Request 3, concurrent"] --> S
  D --> X["Shared across requests: stale tracking, concurrency exceptions, memory growth"]

// BUG: singleton captures a scoped DbContext
builder.Services.AddDbContext<AppDbContext>(o => o.UseSqlServer(cs));   // scoped
builder.Services.AddSingleton<PricingService>();

public sealed class PricingService(AppDbContext db)   // lives forever with ONE DbContext
{
    public Task<decimal> GetAsync(int sku) =>
        db.Prices.Where(p => p.Sku == sku).Select(p => p.Amount).SingleAsync();
}

Without validation, this "works" in a demo, then in production you see "A second operation was started on this context instance", ever-growing change trackers, and data that never refreshes. The same problem appears more subtly when a singleton depends on a transient that itself depends on a scoped service: the chain is only as long-lived as its longest link.

Fixes, in order of preference:

1. Make the consumer scoped if it has no reason to be a singleton.
2. Depend on a factory designed for this: IDbContextFactory<T> (AddDbContextFactory or AddPooledDbContextFactory) and create/dispose a context per operation.
3. Inject IServiceScopeFactory and create a scope per unit of work (background services, message handlers).

builder.Services.AddPooledDbContextFactory<AppDbContext>(o => o.UseSqlServer(cs));

public sealed class PricingService(IDbContextFactory<AppDbContext> factory)  // OK as singleton
{
    public async Task<decimal> GetAsync(int sku, CancellationToken ct)
    {
        await using var db = await factory.CreateDbContextAsync(ct);
        return await db.Prices.Where(p => p.Sku == sku).Select(p => p.Amount).SingleAsync(ct);
    }
}

Scope validation

The default ServiceProvider can validate two things:

• ValidateScopes: throws if a scoped service is resolved from the root provider, or injected into a singleton ("Cannot consume scoped service 'AppDbContext' from singleton 'PricingService'").
• ValidateOnBuild: at builder.Build(), checks that every registered service can be constructed (missing registrations, captive scoped dependencies) instead of failing on the first request that needs it.

Both are enabled automatically when the environment is Development. Many teams turn them on everywhere, or at least in CI and integration tests, because the startup cost is small compared with discovering a captive dependency in production:

builder.Host.UseDefaultServiceProvider(o =>
{
    o.ValidateScopes = true;
    o.ValidateOnBuild = true;
});

Limits: validation cannot see services resolved manually via IServiceProvider.GetService inside your code, or captures you make yourself (storing a scoped instance in a static field). It also cannot detect a disposable transient resolved from the root.

Choosing a lifetime: a practical heuristic

• Holds per-request state or a DbContext? Scoped.
• Stateless, cheap, and only depends on singletons/stateless services? Singleton or transient both work; singleton avoids allocations, transient avoids accidental shared state. Default to scoped or transient unless there is a reason.
• Expensive to create, thread-safe, holds caches or connections (for example ConnectionMultiplexer, JsonSerializerOptions, gRPC channel)? Singleton.
• Needs scoped services but must be a singleton (hosted service, middleware)? Use a scope factory, never constructor-inject the scoped dependency.

Remember that convention-based middleware and IHostedService implementations are effectively singletons, and that an IOptionsSnapshot<T> is scoped (so it cannot be injected into a singleton; use IOptionsMonitor<T>).

Keyed services

Before .NET 8 you had to inject IEnumerable<IPaymentGateway> and pick by a property, or hand-roll a dictionary factory. Keyed registration makes the selection explicit in the container:

builder.Services.AddKeyedScoped<IPaymentGateway, StripeGateway>("stripe");
builder.Services.AddKeyedScoped<IPaymentGateway, AdyenGateway>("adyen");
builder.Services.AddKeyedSingleton<IBlobStore, HotBlobStore>(StorageTier.Hot);   // keys can be any object, e.g. enums

// Constructor injection of a specific implementation
public sealed class RefundService([FromKeyedServices("stripe")] IPaymentGateway gateway) { /* ... */ }

// Minimal API parameter
app.MapPost("/pay/{provider}", async (string provider, PayRequest req, IServiceProvider sp, CancellationToken ct) =>
{
    var gateway = sp.GetKeyedService<IPaymentGateway>(provider);       // runtime key
    return gateway is null
        ? Results.Problem($"Unknown provider '{provider}'", statusCode: 400)
        : Results.Ok(await gateway.ChargeAsync(req, ct));
});

// An implementation can receive the key it was registered with
public sealed class TenantCache([ServiceKey] string tenant, IConnectionMultiplexer redis) { /* ... */ }

• Keys are compared with Equals, so strings are case-sensitive and enums work well.
• KeyedService.AnyKey registers a fallback implementation for any key; .NET 10 fixed inconsistencies in GetKeyedService/GetKeyedServices with AnyKey (a documented behavioral change).
• A keyed registration is not returned when resolving the un-keyed service type; they are separate registrations.

When the key comes from runtime data (request route value, tenant, message header), resolving through IServiceProvider is a mild form of service location. Wrap it behind a small factory interface so business code stays clean and testable:

public interface IPaymentGatewayFactory { IPaymentGateway Get(string provider); }

internal sealed class PaymentGatewayFactory(IServiceProvider sp) : IPaymentGatewayFactory
{
    public IPaymentGateway Get(string provider) =>
        sp.GetKeyedService<IPaymentGateway>(provider)
        ?? throw new UnsupportedProviderException(provider);
}
builder.Services.AddScoped<IPaymentGatewayFactory, PaymentGatewayFactory>();  // scoped: resolves scoped gateways

Factories for runtime parameters

Avoid async work in factory delegates: there is no async resolution, so you end up with .Result. Do async initialization in a hosted service or lazily inside the service.

Scoped services inside singletons and background services

A BackgroundService is registered as a singleton (via AddHostedService). There is no ambient request scope, so constructor-injecting a DbContext is a captive dependency (and scope validation throws). The correct pattern is one scope per unit of work:

sequenceDiagram
  participant W as OutboxWorker singleton
  participant F as IServiceScopeFactory
  participant S as Scope
  participant D as AppDbContext
  loop every batch
    W->>F: CreateAsyncScope
    F-->>W: scope
    W->>S: GetRequiredService AppDbContext
    S-->>W: fresh DbContext
    W->>D: query and SaveChangesAsync
    W->>S: DisposeAsync, context disposed
  end

public sealed class OutboxWorker(
    IServiceScopeFactory scopeFactory,
    ILogger<OutboxWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(5));
        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await using var scope = scopeFactory.CreateAsyncScope();
                var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
                var publisher = scope.ServiceProvider.GetRequiredService<IMessagePublisher>();

                var batch = await db.OutboxMessages
                    .Where(m => m.ProcessedAt == null)
                    .OrderBy(m => m.Id).Take(100)
                    .ToListAsync(stoppingToken);

                foreach (var msg in batch)
                {
                    await publisher.PublishAsync(msg, stoppingToken);
                    msg.ProcessedAt = DateTimeOffset.UtcNow;
                }
                await db.SaveChangesAsync(stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                logger.LogError(ex, "Outbox batch failed");   // don't let one failure kill the host
            }
        }
    }
}

Why per batch and not one scope for the whole loop? A long-lived scope means a long-lived DbContext, whose change tracker grows forever and whose connection state can go stale. Per-unit-of-work scopes give you fresh state and deterministic disposal. The same applies to message consumers (one scope per message) and to singleton services that occasionally need scoped data.

Alternatives to manual scopes

• If the only scoped dependency is a DbContext, inject IDbContextFactory<T> instead — no service locator needed.
• Messaging frameworks (MassTransit, Wolverine, Azure Functions) create a scope per message for you.
• Since .NET 6, an unhandled exception in ExecuteAsync stops the host by default (BackgroundServiceExceptionBehavior.StopHost), so catch per iteration as above unless crashing is what you want.

Side-by-side

Organizing Minimal APIs: route groups and feature modules

The common criticism "Minimal APIs turn Program.cs into a 2,000-line file" is a code organization problem, not a framework one. Use one static class per feature with a Map... extension and a route group that applies shared conventions:

public static class OrderEndpoints
{
    public static IEndpointRouteBuilder MapOrders(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders")
            .WithTags("Orders")
            .RequireAuthorization("orders:read")
            .RequireRateLimiting("per-user");

        group.MapGet("/{id:guid}", GetById).WithName("GetOrder");
        group.MapPost("/", Create).RequireAuthorization("orders:write");
        return app;
    }

    // Results<...> documents every possible response for OpenAPI and is checked by the compiler
    static async Task<Results<Ok<OrderDto>, NotFound>> GetById(
        Guid id, IOrderQueries queries, CancellationToken ct) =>
        await queries.FindAsync(id, ct) is { } order
            ? TypedResults.Ok(order)
            : TypedResults.NotFound();

    static async Task<Created<OrderDto>> Create(
        CreateOrderRequest request, IOrderService service, CancellationToken ct)
    {
        var order = await service.CreateAsync(request, ct);
        return TypedResults.Created($"/api/orders/{order.Id}", order);
    }
}

Why TypedResults over Results? Results.Ok(x) returns IResult, so the OpenAPI generator cannot infer the response type and unit tests must cast. TypedResults.Ok(x) returns Ok<T>; combined with Results<Ok<T>, NotFound> the response metadata is generated automatically and tests can assert on the concrete type without an HTTP server.

.NET 10 built-in validation

builder.Services.AddValidation();   // source-generated; discovers types used by Minimal API handlers

public record CreateOrderRequest(
    [Required, StringLength(64)] string CustomerId,
    [MinLength(1)] List<OrderLine> Lines);

public record OrderLine(
    [Required] string Sku,
    [Range(1, 1000)] int Quantity);

// Opt out for a specific endpoint
group.MapPost("/import", Import).DisableValidation();

Validation runs as an automatically added endpoint filter over query, header and body parameters, including nested objects and collections, records and classes. Failures return 400 with a validation ProblemDetails listing errors per member, and the response can be customized through IProblemDetailsService. Use IValidatableObject for cross-field rules. Two practical notes: the generator only discovers types in the assembly where AddValidation is called (call it in each assembly that defines endpoints), and the APIs moved to the Microsoft.Extensions.Validation package so they can be reused outside HTTP. Teams with complex rules or async checks often still use FluentValidation via an endpoint filter.

Request flow

flowchart LR
  A["HTTP request"] --> B["Middleware: auth, rate limit"]
  B --> C["Route group conventions"]
  C --> D["Parameter binding: route, query, body, DI"]
  D --> E["Validation endpoint filter"]
  E -->|"invalid"| F["400 ValidationProblem"]
  E -->|"valid"| G["Custom endpoint filters"]
  G --> H["Handler returns TypedResults"]
  H --> I["Serialized response"]

When controllers still make sense

• Large existing MVC codebases: migrating for its own sake has little value.
• You rely on MVC-specific features: OData, XML input/output formatters with content negotiation, ApplicationModel conventions, Razor views alongside APIs.
• The team relies heavily on MVC filters and attribute-based conventions.

You can mix both in one app; they share routing, so you can add new features as Minimal API endpoints without touching old controllers.

Configuration sources and precedence

WebApplication.CreateBuilder adds providers in this order (later wins):

1. appsettings.json
2. appsettings.{Environment}.json
3. User secrets (Development only)
4. Environment variables (Orders__MaxItems maps to Orders:MaxItems)
5. Command-line arguments

You then add cloud providers such as Azure Key Vault or Azure App Configuration, typically after the defaults so they override files. JSON file providers reload on change by default, which is what makes IOptionsMonitor useful.

flowchart LR
  A["appsettings.json"] --> M["IConfiguration merged view"]
  B["appsettings.Production.json"] --> M
  C["Environment variables"] --> M
  D["Key Vault / App Configuration"] --> M
  M -->|"Bind section"| O["OrdersOptions"]
  O --> V{"Validate on start"}
  V -->|"invalid"| X["Host fails to start"]
  V -->|"valid"| S["IOptions / Snapshot / Monitor"]

Binding with validation

public sealed class OrdersOptions
{
    public const string Section = "Orders";

    [Required, Url] public string PricingServiceUrl { get; set; } = "";
    [Range(1, 500)]  public int MaxItemsPerOrder { get; set; } = 100;
    public TimeSpan ReservationTtl { get; set; } = TimeSpan.FromMinutes(15);
}

builder.Services.AddOptions<OrdersOptions>()
    .BindConfiguration(OrdersOptions.Section)
    .ValidateDataAnnotations()
    .Validate(o => o.ReservationTtl > TimeSpan.Zero, "ReservationTtl must be positive")
    .ValidateOnStart();          // eager: fail during host startup

For AOT and to avoid reflection, .NET 8+ offers a source-generated validator: declare [OptionsValidator] public partial class OrdersOptionsValidator : IValidateOptions<OrdersOptions>; and register it. There is also the shortcut AddOptionsWithValidateOnStart<T>(). Configuration binding itself can be source generated (EnableConfigurationBindingGenerator, turned on automatically for Native AOT apps).

The three interfaces

public sealed class PricingClient(HttpClient http, IOptionsMonitor<OrdersOptions> options)
{
    public Task<Price?> GetAsync(string sku, CancellationToken ct)
    {
        var o = options.CurrentValue;            // read at use time, not in the constructor
        return http.GetFromJsonAsync<Price>($"{o.PricingServiceUrl}/prices/{sku}", ct);
    }
}

// Named options: same type, different config sections
builder.Services.AddOptions<StorageOptions>("hot").BindConfiguration("Storage:Hot");
builder.Services.AddOptions<StorageOptions>("archive").BindConfiguration("Storage:Archive");
// var hot = monitor.Get("hot");

Note that reloaded values are validated too: with IOptionsMonitor, an invalid reload throws OptionsValidationException when the value is accessed, so treat runtime config edits with the same care as deployments.

Secrets and environments

• Never commit secrets to appsettings*.json. Use user secrets locally and Key Vault with managed identity (or Kubernetes secrets mounted as files/env vars) in Azure.
• Prefer managed identity over connection strings with passwords wherever the target supports Entra ID auth (Azure SQL, Storage, Service Bus).
• Azure App Configuration adds centralized settings, labels per environment, feature flags and a sentinel-key refresh pattern for dynamic reloads across instances.
• .NET 10 preserves explicit null values from configuration sources during binding (previously they were dropped), a documented behavior change worth checking when upgrading.

Configuration in containers and Kubernetes

Twelve-factor style deployments push configuration through the environment. In Kubernetes, map ConfigMaps to environment variables (Orders__MaxItemsPerOrder=200) and mount secrets either as variables or as files read with AddKeyPerFile (one file per key, file name as the key). File mounts update in place when the secret changes, which works with reload-on-change; environment variables only change when the pod restarts. Keep one image for all environments and let configuration differ — never bake environment-specific appsettings into separate images. Finally, log the names of the configuration sources at startup (not their values) so "why is this setting wrong?" can be answered without guessing which provider won.

What the host does

// Worker service (no HTTP)
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHostedService<InvoiceExporter>();
builder.Services.Configure<HostOptions>(o =>
{
    o.ShutdownTimeout = TimeSpan.FromSeconds(25);   // below Kubernetes' 30 s grace period
    o.ServicesStartConcurrently = false;            // default: sequential start
});
await builder.Build().RunAsync();

WebApplication.CreateBuilder builds on the same host. Lifetime events are exposed through IHostApplicationLifetime (ApplicationStarted, ApplicationStopping, ApplicationStopped). For finer control, IHostedLifecycleService (.NET 8+) adds StartingAsync, StartedAsync, StoppingAsync and StoppedAsync hooks around the main calls.

IHostedService vs BackgroundService

The .NET 10 change matters: previously the synchronous part of ExecuteAsync before the first await ran on the startup path and could block other services, a classic "the app never starts listening" bug. Now it is all background. If you genuinely need work done before the app accepts traffic, put it in StartAsync (override and call base.StartAsync), in IHostedLifecycleService.StartingAsync, or in a plain IHostedService.

A well-behaved BackgroundService

public sealed class InvoiceExporter(
    Channel<InvoiceJob> queue,
    IServiceScopeFactory scopes,
    ILogger<InvoiceExporter> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var job in queue.Reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                await using var scope = scopes.CreateAsyncScope();
                var exporter = scope.ServiceProvider.GetRequiredService<IInvoiceExportService>();
                await exporter.ExportAsync(job, stoppingToken);   // pass the token everywhere
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                logger.LogInformation("Shutdown requested; job {JobId} will be retried", job.Id);
                break;
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Export failed for {JobId}", job.Id);  // keep the loop alive
            }
        }
    }
}

By default an unhandled exception escaping ExecuteAsync stops the whole host (BackgroundServiceExceptionBehavior.StopHost, the default since .NET 6). That is usually right for a worker container, since the orchestrator restarts it, but in a web app it means one failing poller takes down the API, so catch per iteration.

Graceful shutdown end to end

sequenceDiagram
  participant K as Kubernetes
  participant H as Host
  participant W as Kestrel
  participant B as BackgroundService
  K->>K: remove pod from endpoints
  K->>H: SIGTERM
  H->>H: ApplicationStopping fires
  H->>W: StopAsync, stop accepting, drain requests
  H->>B: cancel stoppingToken, await ExecuteAsync
  B-->>H: finished or checkpointed
  H->>H: dispose services, ApplicationStopped
  Note over K,H: must finish before terminationGracePeriodSeconds, else SIGKILL

• Align timeouts: ShutdownTimeout < terminationGracePeriodSeconds (30 s default in Kubernetes). If your jobs take minutes, either increase both or make the jobs resumable.
• Endpoint removal races SIGTERM: load balancers may still send traffic for a few seconds. A small preStop sleep (for example 5–10 s) lets routing converge before Kestrel stops accepting connections.
• Make work idempotent or resumable: shutdown can always be ungraceful (OOM kill, node failure). Use at-least-once delivery with idempotent handlers, leases, or checkpoints instead of trusting StopAsync.
• Readiness: flip readiness to unhealthy on ApplicationStopping so no new work is routed.

Why a single, standard error contract

Clients (SPAs, mobile apps, other services) need one predictable error shape to branch on. RFC 9457 (which obsoletes RFC 7807) defines it. Use the type URI or a stable extension such as errorCode as the machine-readable discriminator, title as a short human summary that does not change per occurrence, and detail for the specific occurrence. Always include a correlation/trace ID so support can find the logs.

{
  "type": "https://errors.contoso.com/orders/insufficient-stock",
  "title": "Insufficient stock",
  "status": 409,
  "detail": "SKU 'ABC-123' has 2 units available, 5 requested.",
  "instance": "/api/orders",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errorCode": "ORD-409-STOCK"
}

The pipeline

flowchart TD
  A["Exception thrown in endpoint or middleware"] --> B["ExceptionHandler middleware"]
  B --> C["IExceptionHandler 1: domain exceptions"]
  C -->|"returns true"| Z["ProblemDetails response written"]
  C -->|"returns false"| D["IExceptionHandler 2: validation"]
  D -->|"returns false"| E["Fallback: IProblemDetailsService 500"]
  D -->|"returns true"| Z
  E --> Z

builder.Services.AddProblemDetails(o =>
{
    o.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Instance = $"{ctx.HttpContext.Request.Method} {ctx.HttpContext.Request.Path}";
        ctx.ProblemDetails.Extensions["traceId"] = Activity.Current?.Id ?? ctx.HttpContext.TraceIdentifier;
    };
});
builder.Services.AddExceptionHandler<DomainExceptionHandler>();   // registered order = execution order

var app = builder.Build();
app.UseExceptionHandler();      // uses registered handlers + IProblemDetailsService
app.UseStatusCodePages();       // empty 4xx/5xx responses get ProblemDetails too

public sealed class DomainExceptionHandler(
    IProblemDetailsService problemDetails,
    ILogger<DomainExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext http, Exception exception, CancellationToken ct)
    {
        (int status, string title, string code)? map = exception switch
        {
            NotFoundException        => (404, "Resource not found", "NOT_FOUND"),
            InsufficientStockException => (409, "Insufficient stock", "ORD-409-STOCK"),
            ConcurrencyException     => (412, "Resource was modified", "PRECONDITION_FAILED"),
            _ => null
        };
        if (map is null) return false;                 // let the next handler / default 500 handle it

        logger.LogWarning(exception, "Handled domain exception {ErrorCode}", map.Value.code);
        http.Response.StatusCode = map.Value.status;

        return await problemDetails.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = http,
            Exception = exception,
            ProblemDetails =
            {
                Status = map.Value.status,
                Title = map.Value.title,
                Detail = exception.Message,             // only for messages safe to show clients
                Type = $"https://errors.contoso.com/{map.Value.code.ToLowerInvariant()}",
                Extensions = { ["errorCode"] = map.Value.code }
            }
        });
    }
}

Expected vs unexpected errors

Exceptions are relatively expensive and invisible in signatures, so many teams use a Result type for expected outcomes and keep exceptions for the truly exceptional. Either way, the HTTP edge translates to Problem Details in one place.

Expected failures without exceptions

For outcomes that are part of the business flow, return them explicitly and let the endpoint translate them; the exception handler then stays a safety net for the unexpected:

app.MapPost("/api/orders/{id:guid}/ship", async Task<Results<NoContent, NotFound, ProblemHttpResult>> (
    Guid id, IOrderService orders, CancellationToken ct) =>
    await orders.ShipAsync(id, ct) switch
    {
        ShipResult.Shipped        => TypedResults.NoContent(),
        ShipResult.NotFound       => TypedResults.NotFound(),
        ShipResult.AlreadyShipped => TypedResults.Problem(
            title: "Order already shipped", statusCode: StatusCodes.Status409Conflict,
            type: "https://errors.contoso.com/orders/already-shipped"),
        _ => throw new UnreachableException()
    });

TypedResults.Problem goes through the same ProblemDetails customization, so the shape and trace ID are identical whether the error came from a result or an exception.

.NET 10 diagnostics behavior

Starting with .NET 10, when an IExceptionHandler returns true, the exception handler middleware no longer logs the UnhandledException message, writes the HandledException event, or adds error.type to the http.server.request.duration metric. That is usually what you want for expected domain errors, but it means your handler must log anything you still care about. To restore the old behavior, set ExceptionHandlerOptions.SuppressDiagnosticsCallback to return false.

Request flow

sequenceDiagram
  participant C as Client
  participant A as Authentication middleware
  participant Z as Authorization middleware
  participant E as Endpoint
  participant S as IAuthorizationService
  C->>A: Authorization Bearer token
  A->>A: validate signature, iss, aud, exp
  A->>Z: HttpContext.User with claims
  Z->>Z: evaluate endpoint policy, scope check
  Z-->>C: 401 if unauthenticated, 403 if forbidden
  Z->>E: allowed
  E->>S: AuthorizeAsync user, order, CanCancel
  S-->>E: Succeeded or Failed

401 means "I don't know who you are" (missing/invalid token: the handler challenges); 403 means "I know who you are, and you can't" (the handler forbids). Getting these right matters for clients that refresh tokens on 401.

JWT bearer configuration

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.Authority = "https://login.microsoftonline.com/{tenantId}/v2.0";  // discovers signing keys via OIDC metadata
        o.Audience = "api://orders-api";
        o.MapInboundClaims = false;                  // keep 'sub', 'roles', 'scp' as-is
        o.TokenValidationParameters = new()
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(1),     // default is 5 minutes
            NameClaimType = "name",
            RoleClaimType = "roles"
        };
    });

• Use Authority so keys are fetched and rotated from the identity provider's JWKS; never hard-code a symmetric secret shared across services in production.
• Always validate audience: a token issued for another API in the same tenant must not work against yours.
• Since .NET 8 the handler uses JsonWebTokenHandler by default, and the claims mapping behavior differs slightly from the old JwtSecurityTokenHandler; MapInboundClaims = false avoids the legacy long-URI claim names.
• For Entra ID specifically, Microsoft.Identity.Web (AddMicrosoftIdentityWebApi) wraps this with sensible defaults.

Policies, requirements and handlers

builder.Services.AddAuthorizationBuilder()
    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build()) // secure by default
    .AddPolicy("orders:read",  p => p.RequireClaim("scp", "Orders.Read"))
    .AddPolicy("orders:admin", p => p.RequireRole("OrdersAdmin"))
    .AddPolicy("CanCancelOrder", p => p.AddRequirements(new SameTenantRequirement(), new OrderOwnerOrManagerRequirement()));

builder.Services.AddScoped<IAuthorizationHandler, OrderOwnerOrManagerHandler>();
builder.Services.AddSingleton<IAuthorizationHandler, SameTenantHandler>();

app.MapGroup("/api/orders").RequireAuthorization("orders:read");

All requirements in a policy must succeed. A requirement succeeds if any of its handlers calls context.Succeed(requirement) and none calls context.Fail(). That gives you OR semantics within a requirement (multiple handlers) and AND semantics across requirements.

Resource-based authorization

Endpoint policies run before your handler loads data, so they cannot know who owns order 42. For that, load the resource and ask the authorization service:

public sealed record OrderOwnerOrManagerRequirement : IAuthorizationRequirement;

public sealed class OrderOwnerOrManagerHandler
    : AuthorizationHandler<OrderOwnerOrManagerRequirement, Order>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context, OrderOwnerOrManagerRequirement req, Order order)
    {
        var userId = context.User.FindFirst("sub")?.Value;
        if (order.CustomerId == userId || context.User.IsInRole("StoreManager"))
            context.Succeed(req);
        return Task.CompletedTask;               // not calling Succeed = not satisfied
    }
}

app.MapPost("/api/orders/{id:guid}/cancel", async Task<Results<NoContent, NotFound, ForbidHttpResult>> (
    Guid id, ClaimsPrincipal user, IAuthorizationService auth, IOrderRepository repo, CancellationToken ct) =>
{
    var order = await repo.FindAsync(id, ct);
    if (order is null) return TypedResults.NotFound();

    var result = await auth.AuthorizeAsync(user, order, "CanCancelOrder");
    if (!result.Succeeded) return TypedResults.Forbid();

    order.Cancel();
    await repo.SaveAsync(ct);
    return TypedResults.NoContent();
});

For list endpoints, don't load everything and filter with AuthorizeAsync per item; push the rule into the query (Where(o => o.TenantId == tenantId), EF Core query filters) and keep the handler for single-resource decisions.

The algorithms

All limiters support a QueueLimit with QueueProcessingOrder (oldest or newest first): requests can wait for a permit instead of being rejected immediately. Keep queues small; a big queue converts overload into latency.

Configuration with partitioning

using System.Threading.RateLimiting;

builder.Services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;   // default is 503
    options.OnRejected = async (ctx, ct) =>
    {
        if (ctx.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
            ctx.HttpContext.Response.Headers.RetryAfter = ((int)retryAfter.TotalSeconds).ToString();
        await ctx.HttpContext.Response.WriteAsJsonAsync(
            new { title = "Too many requests" }, cancellationToken: ct);
    };

    // Per-user (or per-IP for anonymous) token bucket
    options.AddPolicy("per-user", http =>
    {
        var key = http.User.FindFirst("sub")?.Value
                  ?? http.Connection.RemoteIpAddress?.ToString()
                  ?? "anonymous";
        return RateLimitPartition.GetTokenBucketLimiter(key, _ => new TokenBucketRateLimiterOptions
        {
            TokenLimit = 20,                                 // burst
            TokensPerPeriod = 10,                            // sustained 10 req/s
            ReplenishmentPeriod = TimeSpan.FromSeconds(1),
            QueueLimit = 0,
            AutoReplenishment = true
        });
    });

    // Protect an expensive endpoint
    options.AddConcurrencyLimiter("exports", o => { o.PermitLimit = 4; o.QueueLimit = 10; });

    // Global safety net for the whole instance
    options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(_ =>
        RateLimitPartition.GetConcurrencyLimiter("global",
            _ => new ConcurrencyLimiterOptions { PermitLimit = 1_000, QueueLimit = 0 }));
});

var app = builder.Build();
app.UseRouting();
app.UseAuthentication();       // so the policy can see the user
app.UseRateLimiter();          // after routing for endpoint-specific policies

app.MapGroup("/api").RequireRateLimiting("per-user");
app.MapPost("/api/reports/export", ExportReport).RequireRateLimiting("exports");
app.MapGet("/health", () => "ok").DisableRateLimiting();

The partition factory is called per request, but the limiter instance per key is created once and reused. Partition keys must have bounded cardinality in practice; keying on arbitrary input (for example a query string) creates unbounded limiter instances.

Where rate limiting belongs

flowchart LR
  C["Clients"] --> E["Edge: WAF / Front Door / APIM"]
  E -->|"global per-key quota, DDoS"| G["Gateway: YARP or APIM"]
  G -->|"tenant quotas"| P1["API pod 1: UseRateLimiter"]
  G --> P2["API pod 2: UseRateLimiter"]
  P1 -->|"concurrency limit"| D[("Database")]
  P2 --> D

• Edge / gateway (Azure Front Door WAF, API Management, YARP with a distributed store) enforces consistent per-client quotas across replicas and blocks abuse before it costs compute.
• In-process limiter protects each instance from overload and protects expensive endpoints; with N replicas a "100/min per user" policy effectively becomes up to N × 100/min unless traffic is sticky.
• For accurate distributed limits inside the app, use a Redis-backed implementation (community packages implement RateLimiter on Redis) and accept the extra round trip.

Correctness details

• Behind a proxy, RemoteIpAddress is the proxy unless UseForwardedHeaders is configured with trusted proxies — otherwise all users share one partition.
• Return 429 with Retry-After so well-behaved clients (and Polly's retry strategy) back off correctly.
• Distinguish rate limiting (fairness and abuse prevention per client) from load shedding (protecting the service as a whole, often via concurrency limits and 503).
• Emit metrics: ASP.NET Core publishes rate-limiting metrics (leased/queued/rejected) in the Microsoft.AspNetCore.RateLimiting meter; alert on sustained rejections.

The options at a glance

HybridCache: the modern default for data

flowchart LR
  R["Request"] --> L1{"L1 in-memory hit?"}
  L1 -->|"yes"| OUT["Return object"]
  L1 -->|"no"| L2{"L2 Redis hit?"}
  L2 -->|"yes"| D["Deserialize, fill L1"]
  D --> OUT
  L2 -->|"no"| F["Single factory call per key, others wait"]
  F --> DB[("Database")]
  F --> W["Write L2 and L1"]
  W --> OUT

builder.Services.AddStackExchangeRedisCache(o =>
    o.Configuration = builder.Configuration.GetConnectionString("redis"));  // becomes L2
builder.Services.AddHybridCache(o =>
{
    o.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(10),          // L2 (and overall) lifetime
        LocalCacheExpiration = TimeSpan.FromMinutes(1)   // L1 shorter to limit staleness
    };
});

public sealed class ProductQueries(HybridCache cache, CatalogDbContext db)
{
    public ValueTask<ProductDto?> GetAsync(int id, CancellationToken ct) =>
        cache.GetOrCreateAsync(
            $"product:{id}",
            async token => await db.Products
                .Where(p => p.Id == id)
                .Select(p => new ProductDto(p.Id, p.Name, p.Price))
                .FirstOrDefaultAsync(token),
            tags: ["products", $"category:{id % 100}"],
            cancellationToken: ct);

    public async Task UpdatePriceAsync(int id, decimal price, CancellationToken ct)
    {
        await db.Products.Where(p => p.Id == id)
            .ExecuteUpdateAsync(s => s.SetProperty(p => p.Price, price), ct);
        await cache.RemoveAsync($"product:{id}", ct);     // invalidate after the write
    }

    public ValueTask InvalidateCatalogAsync(CancellationToken ct) =>
        cache.RemoveByTagAsync("products", ct);
}

Key points: only one caller per key runs the factory at a time (in that instance) and the others await its result; if no IDistributedCache is registered, it works as an L1-only cache with stampede protection; serialization uses System.Text.Json by default and is pluggable. Two caveats: L1 copies on other instances are not actively notified when you remove a key, so they can be stale until LocalCacheExpiration — keep it short for data that changes; and cache keys must never be built from raw user input.

IMemoryCache and IDistributedCache still have their place

• IMemoryCache: tiny, hot, per-instance lookups (feature flags, reference data) where staleness is fine. Set SizeLimit and per-entry Size, or it can grow unbounded.
• IDistributedCache directly: when you need raw bytes, cross-language consumers, or explicit control. Usually HybridCache is a better facade over it.

Output caching vs response caching

builder.Services.AddOutputCache(o =>
{
    o.AddBasePolicy(b => b.Expire(TimeSpan.FromSeconds(30)));
    o.AddPolicy("catalog", b => b
        .Expire(TimeSpan.FromMinutes(5))
        .SetVaryByQuery("page", "category")
        .Tag("catalog"));
});
// builder.Services.AddStackExchangeRedisOutputCache(...) to share across instances

app.UseOutputCache();   // after UseCors / auth middleware

app.MapGet("/api/catalog", GetCatalog).CacheOutput("catalog");
app.MapPost("/api/catalog/items", async (CreateItem cmd, IOutputCacheStore store, CancellationToken ct) =>
{
    // ... create item ...
    await store.EvictByTagAsync("catalog", ct);
    return TypedResults.NoContent();
});

Output caching (.NET 7+) is server-controlled: it ignores client Cache-Control: no-cache by default, coalesces concurrent identical requests, supports tags and eviction, and by default only caches anonymous GET/HEAD 200 responses without cookies. Response caching (UseResponseCaching) follows HTTP caching rules: if the client sends no-cache, it misses. Use [ResponseCache]/Cache-Control headers for browsers and CDNs, and output caching for server-side caching.

Invalidation strategy

• Cache-aside with TTL for most data; pick TTLs from business tolerance for staleness.
• Explicit invalidation on writes (remove key or tag) when staleness is visible to users (prices, permissions).
• Event-driven invalidation across services: publish "ProductChanged" and let consumers evict.
• Never cache per-user data under shared keys; include tenant/user in the key and avoid caching authorization decisions for long.

Problem 1: socket exhaustion

// Anti-pattern: new client per call
public async Task<Rate> GetRateAsync(string currency)
{
    using var client = new HttpClient();               // new handler, new connection pool
    return (await client.GetFromJsonAsync<Rate>($"https://fx.example.com/{currency}"))!;
}   // disposing closes the connection; the socket sits in TIME_WAIT for minutes

HttpClient wraps an HttpMessageHandler (by default SocketsHttpHandler) that owns a connection pool. Disposing the client disposes the handler and its pooled connections. Under load, thousands of closed connections linger in TIME_WAIT, the ephemeral port range runs out, and you get SocketExceptions ("Only one usage of each socket address..." on Windows, "Cannot assign requested address" on Linux) plus extra TLS handshakes for every call.

Problem 2: stale DNS with a singleton client

The "fix" of one static HttpClient keeps connections open indefinitely. If the target's DNS changes (blue-green deployment, failover, a cloud service moving IPs), your process keeps talking to the old IP until the connection breaks. The fix is to bound connection lifetime:

// Option A: long-lived client without DI (console tools, libraries)
private static readonly HttpClient Http = new(new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),    // recycle connections, re-resolve DNS
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1),
    // MaxConnectionsPerServer = 100,                      // default is unlimited
})
{
    Timeout = TimeSpan.FromSeconds(30)
};

IHttpClientFactory: the default for apps with DI

flowchart LR
  T["Typed client CatalogClient, transient"] --> HC["New HttpClient instance"]
  HC --> P["Pooled handler pipeline, reused"]
  P --> D1["DelegatingHandler: auth token"]
  D1 --> D2["Resilience handler"]
  D2 --> S["SocketsHttpHandler, connection pool"]
  F["IHttpClientFactory"] -->|"rotates handler every 2 min"| P

The factory creates cheap HttpClient objects but reuses the expensive handler chain from a pool, replacing it after HandlerLifetime (2 minutes by default) so DNS changes are picked up; expired handlers are disposed once no client uses them. It also gives you central configuration, DelegatingHandler middleware, logging, and the resilience extensions.

builder.Services.AddTransient<BearerTokenHandler>();

builder.Services.AddHttpClient<CatalogClient>(client =>
    {
        client.BaseAddress = new Uri(builder.Configuration["Catalog:BaseUrl"]!);
        client.DefaultRequestHeaders.UserAgent.ParseAdd("orders-api/1.0");
    })
    .AddHttpMessageHandler<BearerTokenHandler>()
    .AddStandardResilienceHandler();       // retries, timeouts, circuit breaker (Polly v8)

public sealed class CatalogClient(HttpClient http)
{
    public async Task<ProductDto?> GetAsync(int id, CancellationToken ct)
    {
        using var response = await http.GetAsync($"products/{id}", ct);
        if (response.StatusCode == HttpStatusCode.NotFound) return null;
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<ProductDto>(ct);
    }
}

Client styles

The typed-client-in-a-singleton trap

Typed clients are registered as transient. If you inject one into a singleton, that singleton holds one HttpClient — and therefore one handler — forever, and you are back to stale DNS. Options: make the consumer scoped/transient, inject IHttpClientFactory and create clients per operation, or configure SocketsHttpHandler with PooledConnectionLifetime as the primary handler and disable handler rotation for that client.

builder.Services.AddHttpClient<CatalogClient>()
    .UseSocketsHttpHandler((handler, _) => handler.PooledConnectionLifetime = TimeSpan.FromMinutes(2))
    .SetHandlerLifetime(Timeout.InfiniteTimeSpan);   // safe to capture in a singleton now

Other production details

• Always dispose HttpResponseMessage (or use GetFromJsonAsync), otherwise connections are not returned to the pool promptly.
• Timeouts: HttpClient.Timeout defaults to 100 seconds; with the resilience handler, configure attempt and total timeouts there instead.
• Streaming: use HttpCompletionOption.ResponseHeadersRead for large downloads so the body isn't buffered.
• Cancellation: pass the request's CancellationToken so abandoned upstream requests stop downstream calls.
• Headers: DefaultRequestHeaders is not thread-safe to mutate after first use; set per-request headers on HttpRequestMessage or in a DelegatingHandler.

OpenAPI generation in .NET 9/10

builder.Services.AddOpenApi("v1", o =>
{
    o.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Orders API";
        doc.Info.Version = "v1";
        return Task.CompletedTask;
    });
    o.AddDocumentTransformer<BearerSecuritySchemeTransformer>();   // add security scheme
});
builder.Services.AddOpenApi("v2");

var app = builder.Build();

app.MapOpenApi();                                    // /openapi/v1.json, /openapi/v2.json
app.MapOpenApi("/openapi/{documentName}.yaml");      // .NET 10: YAML too
if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference();                     // Scalar.AspNetCore UI (third-party)
}

• Metadata comes from the endpoints themselves: TypedResults return types, WithName, WithSummary, WithDescription, WithTags, Produces/ProducesProblem, and in .NET 10 XML doc comments (with GenerateDocumentationFile) via a source generator. WithOpenApi() is deprecated in .NET 10.
• Transformers (document, operation, schema) replace Swashbuckle filters. In .NET 10 they target Microsoft.OpenApi 2.0, so .NET 9 transformers may need updates (for example JsonNode instead of OpenApiAny, interfaces like IOpenApiSchema).
• Build-time generation with Microsoft.Extensions.ApiDescription.Server writes the document during build, which is ideal for client generation and contract checks in CI.

OpenAPI 3.1 changes what generated clients see: nullable types become type: ["string", "null"] rather than nullable: true, and descriptions can sit next to $ref. If a downstream tool only understands 3.0, set options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0.

Versioning strategies

Pick one, document it, and apply it consistently. URL segment versioning is the most common for public APIs because it is obvious and gateway-friendly.

Asp.Versioning with Minimal APIs and per-version documents

builder.Services.AddApiVersioning(o =>
    {
        o.DefaultApiVersion = new ApiVersion(1);
        o.AssumeDefaultVersionWhenUnspecified = false;     // force clients to be explicit
        o.ReportApiVersions = true;                         // api-supported-versions header
        o.ApiVersionReader = new UrlSegmentApiVersionReader();
    })
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'V";                         // group names "v1", "v2"
        o.SubstituteApiVersionInUrl = true;
    });

var versions = app.NewApiVersionSet()
    .HasDeprecatedApiVersion(new ApiVersion(1))
    .HasApiVersion(new ApiVersion(2))
    .Build();

var orders = app.MapGroup("/api/v{version:apiVersion}/orders").WithApiVersionSet(versions);

orders.MapGet("/{id:guid}", GetOrderV1).MapToApiVersion(1);
orders.MapGet("/{id:guid}", GetOrderV2).MapToApiVersion(2);   // new response shape

The API Explorer assigns each endpoint a GroupName ("v1", "v2"). Microsoft.AspNetCore.OpenApi's default ShouldInclude puts an endpoint in a document when its group name matches the document name (or it has none), so AddOpenApi("v1") and AddOpenApi("v2") produce separate documents. Override ShouldInclude (a Func<ApiDescription, bool>) for custom rules.

flowchart LR
  E["Endpoints with ApiVersionSet"] --> X["Asp.Versioning API Explorer"]
  X -->|"GroupName v1"| D1["AddOpenApi v1"]
  X -->|"GroupName v2"| D2["AddOpenApi v2"]
  D1 --> J1["GET openapi/v1.json"]
  D2 --> J2["GET openapi/v2.json"]
  J1 --> UI["Scalar or Swagger UI"]
  J2 --> UI
  J2 --> GEN["Client generation: Kiota, NSwag, openapi-typescript"]

Versioning policy matters more than mechanics

• Additive changes are not breaking: new optional fields, new endpoints, new enum values if clients tolerate unknown values. Do not bump versions for them.
• Breaking: removing or renaming fields, changing types or semantics, making optional input required, changing status codes or error shapes.
• Deprecation: mark versions deprecated (reported in api-deprecated-versions), add Deprecation/Sunset headers, announce timelines, and watch telemetry per version before removal.
• Contract testing: generate the OpenAPI document in CI and diff it against the last release (tools like oasdiff) to catch accidental breaking changes.

1. Why "works locally" is misleading

flowchart LR
  subgraph Local["Local development"]
    B1["Browser localhost:5173"] --> V["Vite dev proxy"]
    V -->|"server-to-server, no CORS"| A1["API localhost:5001"]
  end
  subgraph Prod["Production"]
    B2["Browser app.contoso.com"] -->|"OPTIONS preflight"| G["Front Door / App Gateway / Ingress"]
    G --> A2["API api.contoso.com"]
  end

CORS is enforced by the browser, not the server. A request from https://app.contoso.com to https://api.contoso.com is cross-origin (different host). For "non-simple" requests — JSON bodies (Content-Type: application/json), Authorization headers, PUT/DELETE — the browser first sends OPTIONS with Origin, Access-Control-Request-Method and Access-Control-Request-Headers, and only sends the real request if the response allows it.

2. Hypotheses and how to confirm each

Reproduce outside the browser to see raw headers:

curl -i -X OPTIONS https://api.contoso.com/api/orders \
  -H "Origin: https://app.contoso.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: authorization,content-type"
# Expect 204 with:
#   Access-Control-Allow-Origin: https://app.contoso.com
#   Access-Control-Allow-Methods: POST
#   Access-Control-Allow-Headers: authorization,content-type
#   Access-Control-Allow-Credentials: true   (only if you use credentials)
#   Vary: Origin

3. A correct configuration

var allowedOrigins = builder.Configuration.GetSection("Cors:AllowedOrigins").Get<string[]>() ?? [];

builder.Services.AddCors(o => o.AddPolicy("spa", p => p
    .WithOrigins(allowedOrigins)                 // e.g. ["https://app.contoso.com"] — no trailing slash
    .WithMethods("GET", "POST", "PUT", "DELETE")
    .WithHeaders("Authorization", "Content-Type", "X-Correlation-Id")
    .WithExposedHeaders("Location", "ETag")
    .AllowCredentials()                          // only if cookies are really needed
    .SetPreflightMaxAge(TimeSpan.FromMinutes(10))));

var app = builder.Build();
app.UseForwardedHeaders();
app.UseExceptionHandler();
app.UseRouting();
app.UseCors("spa");          // before auth, so preflight is answered without credentials
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers().RequireCors("spa");

The CORS middleware answers a valid preflight itself (short-circuits with 204), so authorization never sees it. SetPreflightMaxAge lets browsers cache preflight results, removing an extra round trip per call.

Credentials across origins: the cookie trap

If the SPA authenticates with cookies, CORS is only half the story. The browser sends cookies cross-origin only when the request uses credentials: "include" (or withCredentials), the response allows credentials for that exact origin, and the cookie's SameSite attribute permits it. app.contoso.com and api.contoso.com are cross-origin but same-site, so SameSite=Lax cookies still flow; an API on contoso-api.azurewebsites.net is cross-site, so cookies need SameSite=None; Secure and are increasingly blocked as third-party cookies. That is a strong argument for putting the API under the same site as the SPA, or using a BFF.

4. Prove it and prevent regressions

• Add a smoke test in the deployment pipeline that sends the preflight above against each environment and asserts the allow headers.
• Keep allowed origins in configuration per environment (and validate them at startup with options validation).
• Document which layer owns CORS (app vs gateway) to avoid double headers — two Access-Control-Allow-Origin values also fail.
• Consider eliminating CORS: host the SPA and API under the same site (reverse proxy path /api, or a BFF). No cross-origin, no preflight latency, simpler cookie handling.

Structured logging done right

// Bad: string interpolation — one unique message per order, no queryable properties,
// and the string is built even if Information is disabled
logger.LogInformation($"Order {order.Id} shipped to {order.Country}");

// Good: message template + properties
logger.LogInformation("Order {OrderId} shipped to {Country}", order.Id, order.Country);
// JSON sink output: { "OrderId": "…", "Country": "NL", "MessageTemplate": "Order {OrderId} shipped to {Country}" }

Placeholders are matched by position, not name, and their names become property keys, so keep names consistent across the codebase (OrderId, not orderId/Id/order). Pass exceptions as the first argument (LogError(ex, "...")) so sinks capture the type and stack trace as structured data.

Levels, categories and filtering

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Warning",
      "Orders.Payments": "Debug"
    }
  }
}

The category is the full type name of T in ILogger<T>; filters match by prefix, so you can turn up one namespace without flooding the rest. Filtering happens before formatting, so disabled levels are cheap — unless you did work to build the arguments.

LoggerMessage source generator for hot paths

public static partial class OrderLog
{
    [LoggerMessage(EventId = 1001, Level = LogLevel.Information,
        Message = "Order {OrderId} shipped to {Country} in {ElapsedMs} ms")]
    public static partial void OrderShipped(this ILogger logger, Guid orderId, string country, long elapsedMs);

    [LoggerMessage(EventId = 1002, Level = LogLevel.Warning,
        Message = "Payment retry {Attempt} for order {OrderId}")]
    public static partial void PaymentRetry(this ILogger logger, int attempt, Guid orderId, Exception? ex);
}

// usage
logger.OrderShipped(order.Id, order.Country, sw.ElapsedMilliseconds);

What you gain over logger.LogInformation(template, args):

• No params object[] allocation and no boxing of value-type arguments.
• The template is parsed at compile time; the generated method checks IsEnabled first.
• Compile-time validation: placeholder/parameter mismatches become build errors.
• Stable EventIds you can alert on, and a single catalog of log events per area.

The CA1848 analyzer ("use the LoggerMessage delegates") nudges you toward this. Related packages in Microsoft.Extensions.Telemetry add [LogProperties] to log an object's properties and data classification plus redaction (Microsoft.Extensions.Compliance.Redaction) to keep personal data out of logs.

Scopes and correlation

using (logger.BeginScope(new Dictionary<string, object>
{
    ["TenantId"] = tenant.Id,
    ["OrderId"] = order.Id
}))
{
    logger.LogInformation("Reserving stock");     // carries TenantId and OrderId
    await inventory.ReserveAsync(order, ct);
}

ASP.NET Core already adds request scopes, and when an Activity is active, providers can include TraceId/SpanId, which is what lets you jump from a log line to the distributed trace.

Pipeline options: built-in + OpenTelemetry vs Serilog

flowchart LR
  C["Your code: ILogger"] --> F["Microsoft.Extensions.Logging filters"]
  F --> P1["Console JSON provider"]
  F --> P2["OpenTelemetry provider"]
  P2 --> O["OTLP exporter"]
  O --> B["Collector: Azure Monitor, Grafana, Seq, Aspire dashboard"]
  F --> S["Serilog provider"]
  S --> SE["Enrichers"]
  SE --> SK["Sinks: Seq, Elastic, files, App Insights"]

// Option A: built-in logging exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(o =>
{
    o.IncludeScopes = true;
    o.IncludeFormattedMessage = true;
});
builder.Services.AddOpenTelemetry().UseOtlpExporter();   // logs, traces, metrics together

// Option B: Serilog as the logging pipeline (Serilog.AspNetCore)
builder.Services.AddSerilog((services, lc) => lc
    .ReadFrom.Configuration(builder.Configuration)
    .ReadFrom.Services(services)
    .Enrich.FromLogContext()
    .WriteTo.Console(new Serilog.Formatting.Compact.RenderedCompactJsonFormatter()));
// app.UseSerilogRequestLogging();   // one summary event per request instead of several

Serilog's strengths are its mature sink ecosystem, enrichers, destructuring ({@Order}) and request-logging middleware. The built-in stack with OpenTelemetry is vendor-neutral and correlates logs with traces and metrics natively. Many teams use Serilog with an OpenTelemetry sink to get both. Whatever you choose, code against ILogger<T>, not Serilog.Log statics, so libraries and tests stay provider-agnostic.

Three probes, three different consequences

The most important thing to understand is what the orchestrator does when a probe fails, because that determines what the probe should check.

If liveness checks SQL and the database blips, Kubernetes restarts every replica at once. The restarts don't fix the database, cold starts add load, and you've turned a dependency hiccup into a full outage. Readiness failing for all pods is also an outage, but a recoverable one with no restarts — and for truly shared dependencies even readiness checks deserve thought (see follow-ups).

Implementation in ASP.NET Core

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
    .AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
    .AddDbContextCheck<OrdersDbContext>(tags: ["ready"])        // Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
    .AddCheck<RedisHealthCheck>("redis", HealthStatus.Degraded, tags: ["ready"])
    .AddCheck<StartupHealthCheck>("startup", tags: ["startup"]);

builder.Services.AddSingleton<StartupHealthCheck>();
builder.Services.AddHostedService<WarmupService>();

var app = builder.Build();

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("live")
}).DisableHttpMetrics();

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,   // still take traffic
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
}).DisableHttpMetrics();

app.MapHealthChecks("/health/startup", new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("startup")
});

public sealed class RedisHealthCheck(IConnectionMultiplexer redis) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken ct = default)
    {
        try
        {
            var latency = await redis.GetDatabase().PingAsync();
            return latency < TimeSpan.FromMilliseconds(200)
                ? HealthCheckResult.Healthy($"ping {latency.TotalMilliseconds} ms")
                : HealthCheckResult.Degraded($"slow ping {latency.TotalMilliseconds} ms");
        }
        catch (Exception ex)
        {
            return new HealthCheckResult(context.Registration.FailureStatus, "redis unreachable", ex);
        }
    }
}

public sealed class StartupHealthCheck : IHealthCheck
{
    private volatile bool _ready;
    public void MarkReady() => _ready = true;
    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext c, CancellationToken ct = default) =>
        Task.FromResult(_ready ? HealthCheckResult.Healthy() : HealthCheckResult.Unhealthy("warming up"));
}

Notes: health checks run on every probe request, each with a timeout you can set per registration (timeout: parameter). Use failureStatus: Degraded for non-critical dependencies so the app keeps receiving traffic with reduced functionality. Community packages (the AspNetCore.HealthChecks.* family) provide ready-made checks for SQL Server, PostgreSQL, Redis, RabbitMQ, Azure services and more.

The Kubernetes side

containers:
  - name: orders-api
    image: contoso/orders-api:1.42.0
    ports: [{ containerPort: 8080 }]
    startupProbe:
      httpGet: { path: /health/startup, port: 8080 }
      periodSeconds: 5
      failureThreshold: 30        # up to 150 s to boot
    livenessProbe:
      httpGet: { path: /health/live, port: 8080 }
      periodSeconds: 10
      timeoutSeconds: 2
      failureThreshold: 3
    readinessProbe:
      httpGet: { path: /health/ready, port: 8080 }
      periodSeconds: 5
      timeoutSeconds: 3
      failureThreshold: 2

stateDiagram-v2
  [*] --> Starting
  Starting --> Running: startup probe passes
  Starting --> Restarted: startup limit exceeded
  Running --> NotReady: readiness fails
  NotReady --> Running: readiness passes
  Running --> Restarted: liveness fails N times
  NotReady --> Restarted: liveness fails N times
  Restarted --> Starting

Graceful shutdown and readiness

When a pod is terminated Kubernetes sends SIGTERM and, concurrently, removes it from endpoints — but kube-proxy and ingress controllers update asynchronously, so a few requests still arrive after SIGTERM. The generic host handles SIGTERM, stops accepting new connections and waits up to HostOptions.ShutdownTimeout (30 s by default) for in-flight requests. Common hardening: a short preStop sleep (5–10 s) so routing catches up before Kestrel stops listening, and terminationGracePeriodSeconds larger than the host shutdown timeout. Flip readiness to unhealthy on IHostApplicationLifetime.ApplicationStopping if you have long-lived connections.

Beyond probes

• Publishing: IHealthCheckPublisher runs checks periodically and pushes results (e.g. to metrics) — useful for dashboards without hammering endpoints.
• Security: detailed JSON output (dependency names, exception messages) should not be public. Keep probe endpoints minimal, put rich output behind RequireAuthorization() or RequireHost("*:9090") on a management port.
• Aspire: the ServiceDefaults template maps /health and /alive and tags a "self" check as live; by default it only maps them in Development, precisely because of the exposure concern.
• Azure: App Service Health check and Container Apps probes follow the same semantics — App Service removes unhealthy instances from the load balancer and eventually replaces them.

Transports and negotiation

The client first calls POST /hub/negotiate, receives a connection token and the list of supported transports, then connects. Fallback order:

Protocols on top: JSON (default) or MessagePack (binary, smaller, faster). Keep-alive pings (default 15 s server interval, 30 s client timeout) detect dead connections. Since .NET 8 there is stateful reconnect: the client buffers and replays messages after a brief disconnect (WithStatefulReconnect() on the client, AllowStatefulReconnects on the hub endpoint).

Hubs, groups and pushing from outside the hub

public interface IOrderClient
{
    Task OrderStatusChanged(Guid orderId, string status);
}

[Authorize]
public sealed class OrdersHub : Hub<IOrderClient>
{
    public Task Subscribe(Guid orderId) =>
        Groups.AddToGroupAsync(Context.ConnectionId, $"order-{orderId}");

    public override async Task OnConnectedAsync()
    {
        var tenant = Context.User!.FindFirst("tenant_id")!.Value;
        await Groups.AddToGroupAsync(Context.ConnectionId, $"tenant-{tenant}");
        await base.OnConnectedAsync();
    }
}

// Program.cs
builder.Services.AddSignalR()
    .AddMessagePackProtocol();
app.MapHub<OrdersHub>("/hubs/orders");

// Anywhere else (controller, background service, message consumer)
public sealed class OrderStatusNotifier(IHubContext<OrdersHub, IOrderClient> hub)
{
    public Task NotifyAsync(Guid orderId, string status, CancellationToken ct) =>
        hub.Clients.Group($"order-{orderId}").OrderStatusChanged(orderId, status);
}

Key facts: hub instances are transient — one per invocation — so never store state in hub fields; use Context.Items, a store, or groups. Group membership is not persisted and is lost on reconnect, so re-join in OnConnectedAsync. Clients.User(id) targets all connections of a user using IUserIdProvider (default: the NameIdentifier claim). Browsers can't set headers on WebSockets, so the JS client sends the bearer token as access_token in the query string; configure JwtBearerEvents.OnMessageReceived to read it for hub paths and make sure your logs do not record query strings.

Why scale-out is needed

A connection is pinned to the server that accepted it. If an API call lands on server B and wants to notify a user connected to server A, server B has no socket to write to. Also, SSE and Long Polling make multiple HTTP requests per logical connection, so without sticky sessions the negotiate and subsequent requests may hit different servers and fail. (WebSockets-only with SkipNegotiation avoids stickiness for the connection itself, but you still need a backplane for cross-server messages.)

flowchart LR
  subgraph Backplane["Option A: Redis backplane"]
    C1["Clients"] --> LB["LB with sticky sessions"]
    LB --> S1["App server 1"]
    LB --> S2["App server 2"]
    S1 <-->|"pub/sub"| R[("Redis")]
    S2 <-->|"pub/sub"| R
  end
  subgraph Managed["Option B: Azure SignalR Service"]
    C2["Clients"] -->|"WebSocket"| AS["Azure SignalR"]
    A1["App server 1"] -->|"server connections"| AS
    A2["App server 2"] -->|"server connections"| AS
  end

Option A: Redis backplane

// Microsoft.AspNetCore.SignalR.StackExchangeRedis
builder.Services.AddSignalR()
    .AddStackExchangeRedis(builder.Configuration.GetConnectionString("redis")!, o =>
    {
        o.Configuration.ChannelPrefix = RedisChannel.Literal("orders-app");
    });

Every server publishes every outgoing message to Redis pub/sub and every server receives every message, then delivers to its local connections. Pros: you control it, cheap, works on any host. Cons: sticky sessions still required, each server still holds thousands of sockets (memory, file descriptors), Redis pub/sub is fire-and-forget (messages during a Redis outage are lost), and broadcast traffic grows with servers × messages. Fine for tens of thousands of connections; gets painful beyond.

Option B: Azure SignalR Service

// Microsoft.Azure.SignalR
builder.Services.AddSignalR().AddAzureSignalR();   // reads Azure:SignalR:ConnectionString

Clients negotiate with your app but are redirected to connect to the service. Your servers keep a small pool of server connections to the service; the service routes messages. Your app becomes effectively stateless for connections, no sticky sessions are needed, and the service scales by units to very large connection counts. "Serverless" mode even lets Azure Functions push messages without a hub server. Costs: per-unit pricing and message quotas, another managed dependency, and a hop of latency. Since it supports managed identity, avoid connection strings with keys in production.

Production checklist

• Treat SignalR as a notification channel, not a source of truth: on reconnect, the client should re-fetch state over HTTP because messages may have been missed.
• Configure proxies/ingress for WebSockets (timeouts > keep-alive, Upgrade/Connection headers).
• Bound message sizes (MaximumReceiveMessageSize, default 32 KB) and validate hub inputs like any API.
• Authorize group joins — Subscribe(orderId) above must check the user can see that order, or anyone can listen to anyone's updates.
• Monitor connection counts and message rates (SignalR and Kestrel emit metrics such as signalr.server.active_connections).

How it works

You define services and messages in a .proto file. Grpc.Tools generates a base class for the server and a client class at build time. On the wire each call is an HTTP/2 stream: request and response messages are length-prefixed protobuf frames, and the status (grpc-status, grpc-message) arrives in HTTP trailers. HTTP/2 multiplexing lets many concurrent calls share one TCP connection.

syntax = "proto3";
option csharp_namespace = "Contoso.Inventory.Grpc";
import "google/api/annotations.proto";

service Inventory {
  rpc GetStock (GetStockRequest) returns (StockReply) {
    option (google.api.http) = { get: "/v1/stock/{sku}" };   // JSON transcoding
  }
  rpc WatchStock (WatchRequest) returns (stream StockReply);  // server streaming
  rpc UploadCounts (stream CountLine) returns (UploadSummary); // client streaming
}

message GetStockRequest { string sku = 1; }
message StockReply { string sku = 1; int32 available = 2; }
message WatchRequest { repeated string skus = 1; }
message CountLine { string sku = 1; int32 counted = 2; }
message UploadSummary { int32 lines = 1; }

Field numbers, not names, are the contract. Never reuse or renumber them; mark removed ones reserved. Adding fields is backward compatible, which is why protobuf evolves more safely than ad-hoc JSON.

Server and client in ASP.NET Core

// Server: Grpc.AspNetCore (+ Microsoft.AspNetCore.Grpc.JsonTranscoding)
builder.Services.AddGrpc(o => o.EnableDetailedErrors = builder.Environment.IsDevelopment())
    .AddJsonTranscoding();
app.MapGrpcService<InventoryService>();

public sealed class InventoryService(IStockStore store) : Inventory.InventoryBase
{
    public override async Task<StockReply> GetStock(GetStockRequest request, ServerCallContext context)
    {
        var qty = await store.GetAsync(request.Sku, context.CancellationToken)
                  ?? throw new RpcException(new Status(StatusCode.NotFound, $"SKU {request.Sku} not found"));
        return new StockReply { Sku = request.Sku, Available = qty };
    }

    public override async Task WatchStock(WatchRequest request,
        IServerStreamWriter<StockReply> responseStream, ServerCallContext context)
    {
        await foreach (var change in store.WatchAsync(request.Skus, context.CancellationToken))
            await responseStream.WriteAsync(new StockReply { Sku = change.Sku, Available = change.Qty });
    }
}

// Client: Grpc.Net.ClientFactory
builder.Services.AddGrpcClient<Inventory.InventoryClient>(o => o.Address = new Uri("https://inventory"))
    .AddStandardResilienceHandler();   // retries/timeouts via Microsoft.Extensions.Http.Resilience

var reply = await client.GetStockAsync(new GetStockRequest { Sku = "ABC" },
    deadline: DateTime.UtcNow.AddSeconds(2), cancellationToken: ct);

Deadlines are first-class: the client sends grpc-timeout, the server sees it on context.Deadline and context.CancellationToken fires when it expires. Propagate the token down to the database — that's what prevents abandoned work piling up under load. With EnableCallContextPropagation() on a client registered via the factory, deadlines and cancellation flow automatically from an incoming gRPC call to outgoing ones.

gRPC vs REST

Good fits: internal microservice calls with high call rates, polyglot back ends that benefit from a strict contract, real-time streams (telemetry, price feeds), and mobile clients on constrained networks. Poor fits: public APIs for third parties, anything that benefits from HTTP caching, and teams without the discipline to version .proto files.

Streaming shapes

sequenceDiagram
  participant C as Client
  participant S as Inventory service
  C->>S: GetStock unary request
  S-->>C: StockReply
  C->>S: WatchStock request
  S-->>C: StockReply 1
  S-->>C: StockReply 2
  S-->>C: StockReply n until cancel or deadline
  C->>S: UploadCounts line 1
  C->>S: UploadCounts line n then complete
  S-->>C: UploadSummary

Long-lived streams need care: send periodic keep-alives (SocketsHttpHandler.KeepAlivePingDelay), handle reconnection with a resume token, and remember that a stream pins work to one server.

JSON transcoding, gRPC-Web, and load balancing

• JSON transcoding (.NET 7+): annotate RPCs with google.api.http and call AddJsonTranscoding(); the same service answers GET /v1/stock/ABC with JSON. Add Microsoft.AspNetCore.Grpc.Swagger for OpenAPI generation of the transcoded endpoints. Great for exposing an internal gRPC service to a browser or partner without a second implementation; unary and server streaming are supported.
• gRPC-Web: app.UseGrpcWeb() plus .EnableGrpcWeb() lets browsers (and Blazor WASM) call gRPC over HTTP/1.1 with unary and server streaming only.
• Load balancing: an L4 balancer distributes connections, and one HTTP/2 connection carries all calls, so one pod can get all the load. Use an L7 proxy that balances per request (Envoy, YARP, a service mesh, Azure Container Apps ingress), or grpc-dotnet client-side balancing with a dns:/// address and the round_robin policy against a headless Kubernetes service.
• HTTP/2 requirement: Kestrel endpoints must allow HTTP/2. Without TLS (internal cluster traffic) configure the endpoint as Http2 only, since cleartext HTTP/2 can't be negotiated via ALPN.

The four modes

Streaming rendering ([StreamRendering]) complements Static SSR: the page is sent immediately with placeholders and updated on the same response as async work completes, giving perceived speed without interactivity.

Configuring and applying render modes

// Program.cs
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(Client._Imports).Assembly);

@* Per page or per component instance *@
@page "/orders"
@rendermode InteractiveServer

<OrderSearch @rendermode="InteractiveAuto" />

@* Disable prerendering for a component that touches browser-only APIs *@
<MapView @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

Render modes propagate down the tree: children of an interactive component inherit its mode, and you can't switch to a different interactive mode inside it. Parameters passed across the boundary from a static parent to an interactive child must be serializable (no RenderFragment child content from a static parent into a WASM component). Components using InteractiveWebAssembly or InteractiveAuto must live in the .Client project so their assembly can be downloaded.

Prerendering and the double-load problem

sequenceDiagram
  participant B as Browser
  participant S as Server
  B->>S: GET /orders
  S->>S: Prerender, OnInitializedAsync loads orders
  S-->>B: HTML plus persisted state blob
  B->>S: Start circuit or download WASM
  Note over B,S: Component initializes again in interactive mode
  B->>B: Restore orders from state, no second DB call

Prerendering gives fast first paint and SEO, but the component runs OnInitializedAsync twice: once during prerender, once when it becomes interactive. Without persistence you query the database twice and the UI flickers from "data" to "loading" to "data". Before .NET 10 you wrote boilerplate with PersistentComponentState.RegisterOnPersisting and TryTakeFromJson. In .NET 10:

@page "/orders"
@rendermode InteractiveAuto
@inject IOrderService Orders

@code {
    [PersistentState]
    public List<OrderSummary>? Items { get; set; }   // must be public

    protected override async Task OnInitializedAsync()
    {
        Items ??= await Orders.GetRecentAsync();       // only hits the service if not restored
    }
}

Options on the attribute: AllowUpdates = true lets enhanced navigation refresh the persisted value (by default it's only taken on first interactive load), and RestoreBehavior (SkipInitialValue, SkipLastSnapshot) controls restoring after prerender vs after reconnection. Services can participate too via RegisterPersistentService, and custom serializers via PersistentComponentStateSerializer<T>.

Circuit state in .NET 10

Interactive Server keeps UI state in server memory. Historically, if the WebSocket dropped longer than the reconnection window (mobile backgrounded the tab, network blip), the circuit was gone and the user lost unsaved work. .NET 10 can persist circuit state and resume it on a new circuit as long as the page wasn't fully reloaded, and also allows proactively pausing idle circuits to free server memory. The template also ships a ReconnectModal component (CSP-friendly) with a new retrying state. This narrows, but does not remove, the fundamental trade-off of Server mode: per-user server memory and latency-sensitive UX.

Choosing in practice

• Default everything to Static SSR; add interactivity only where needed ("islands"). Marketing, catalogue and read-heavy pages stay static and cacheable.
• Internal line-of-business apps on low-latency networks: InteractiveServer is productive (direct DB access, no API layer) and cheap to download.
• Public apps with many concurrent users or offline needs: WebAssembly or Auto, backed by a proper HTTP API with auth. Treat WASM code as public — no secrets, authorize on the server.
• For Auto, abstract data access behind an interface with a server implementation (direct) and a client implementation (HTTP); register both in the respective projects.

XSS: output encoding first, CSP second

Razor (@Model.Name) and Blazor encode by default. XSS appears when you bypass that: @Html.Raw, MarkupString in Blazor, building HTML strings in C#, injecting data into inline <script> blocks, or returning user content with Content-Type: text/html. For rich text, sanitize with an allow-list sanitizer (for example HtmlSanitizer) on input and render through a safe path. In SPAs the same applies to dangerouslySetInnerHTML.

Defence in depth: a Content-Security-Policy with nonces or hashes and no unsafe-inline stops most injected scripts from executing even if encoding fails. Set cookies HttpOnly so stolen-script XSS can't read the session cookie.

CSRF and antiforgery

CSRF exploits ambient credentials: the browser automatically attaches cookies to a cross-site form post. Tokens sent in an Authorization header are not ambient, so pure bearer-token APIs are not CSRF-prone (but storing tokens in JS has its own XSS risk). ASP.NET Core's antiforgery issues a cookie token plus a request token that must be echoed back in a form field or header.

builder.Services.AddAntiforgery(o => o.HeaderName = "X-XSRF-TOKEN");
builder.Services.AddControllersWithViews(o =>
    o.Filters.Add(new AutoValidateAntiforgeryTokenAttribute()));   // all unsafe verbs in MVC

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();   // minimal APIs: validates endpoints that bind [FromForm] automatically

app.MapPost("/profile", ([FromForm] ProfileForm form) => TypedResults.Ok());   // token required

// SPA served by the same origin: hand the request token to JS via a readable cookie
app.MapGet("/antiforgery/token", (IAntiforgery af, HttpContext ctx) =>
{
    var tokens = af.GetAndStoreTokens(ctx);
    ctx.Response.Cookies.Append("XSRF-TOKEN", tokens.RequestToken!,
        new CookieOptions { HttpOnly = false, Secure = true, SameSite = SameSiteMode.Strict });
    return Results.NoContent();
}).RequireAuthorization();

SameSite=Lax (the browser default) already blocks most cross-site POSTs with cookies, and Strict blocks more, but SameSite is a mitigation, not a replacement: it treats sibling subdomains as same-site and older clients differ. Keep tokens for cookie-authenticated state changes, and never change state on GET.

SQL injection

// Safe: FormattableString -> parameters
var users = await db.Users.FromSql($"SELECT * FROM Users WHERE Email = {email}").ToListAsync();

// Unsafe: string concatenation into a raw API (EF 10 ships an analyzer warning for this)
var bad = db.Users.FromSqlRaw("SELECT * FROM Users WHERE Email = '" + email + "'");

// Dynamic identifiers can't be parameters: allow-list them
var column = sort switch { "name" => "Name", "created" => "CreatedAt", _ => "Id" };

LINQ queries are always parameterized. Danger zones are FromSqlRaw/ExecuteSqlRaw, Dapper with interpolated SQL strings (Dapper parameterizes only the param object), dynamic ORDER BY and stored procedures that build dynamic SQL internally. Least-privilege DB logins limit the blast radius.

Data Protection: the stack nobody notices until it breaks

Cookie authentication, antiforgery tokens, TempData and Identity tokens are encrypted and signed with keys from the Data Protection system. Keys rotate every 90 days by default. By default they're stored locally (user profile or, in containers, an in-container folder) — so on container restart or with multiple replicas, instances can't decrypt each other's cookies: users are logged out randomly and antiforgery validation fails.

// Azure.Extensions.AspNetCore.DataProtection.Blobs + .Keys
builder.Services.AddDataProtection()
    .SetApplicationName("contoso-shop")                       // same across all instances
    .PersistKeysToAzureBlobStorage(new Uri(blobUri), new DefaultAzureCredential())
    .ProtectKeysWithAzureKeyVault(new Uri(keyIdentifier), new DefaultAzureCredential());

Alternatives: PersistKeysToDbContext (EF Core), Redis, or a file share. Encrypt keys at rest with Key Vault or a certificate. You can also use the API directly via IDataProtector for short-lived tokens (password-reset links, signed state), with purpose strings isolating consumers.

Secrets and configuration

flowchart LR
  Dev["Local dev"] -->|"dotnet user-secrets"| Cfg["IConfiguration"]
  KV[("Azure Key Vault")] -->|"managed identity"| Cfg
  Env["Env vars from platform"] --> Cfg
  Cfg --> App["ASP.NET Core app"]
  CI["CI pipeline"] -->|"OIDC federation, no stored secret"| Azure["Azure deploy"]

// Azure.Extensions.AspNetCore.Configuration.Secrets
if (builder.Environment.IsProduction())
{
    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new DefaultAzureCredential());   // managed identity in Azure, dev credentials locally
}
// Key Vault secret "ConnectionStrings--Orders" maps to config key "ConnectionStrings:Orders"

Better still: avoid secrets entirely. Use managed identity tokens for Azure SQL, Storage, Service Bus and Key Vault so there's no password to leak or rotate. Prefer Key Vault references in App Service/Container Apps or the CSI secrets driver in AKS over copying secrets into environment variables by hand.

Transport and headers checklist

Lifetime: why scoped and short

The context holds a change tracker (identity map plus snapshots), an open-on-demand connection, and possibly a transaction. Keeping one alive for long means unbounded memory growth, stale data (the identity map returns already-tracked instances instead of fresh DB values) and concurrency bugs because it's not thread-safe. One context per HTTP request matches the unit-of-work boundary perfectly.

How change tracking works

When a tracked query materializes an entity, EF stores it in the identity map keyed by primary key and keeps a snapshot of original property values. On SaveChanges, DetectChanges compares current values with snapshots and generates INSERT/UPDATE/DELETE for Added/Modified/Deleted entries. Only changed columns go into the UPDATE.

stateDiagram-v2
  [*] --> Detached
  Detached --> Added: Add
  Detached --> Unchanged: Attach or tracked query
  Unchanged --> Modified: changed + DetectChanges
  Unchanged --> Deleted: Remove
  Added --> Unchanged: SaveChanges
  Modified --> Unchanged: SaveChanges
  Deleted --> Detached: SaveChanges

var order = await db.Orders.SingleAsync(o => o.Id == id, ct);   // tracked, Unchanged
order.Status = OrderStatus.Shipped;                               // still Unchanged until DetectChanges
Console.WriteLine(db.Entry(order).State);                          // Entry() calls DetectChanges -> Modified
await db.SaveChangesAsync(ct);                                     // UPDATE Orders SET Status = @p0 WHERE Id = @p1

// Disconnected update (e.g. from a DTO): attach and mark only what changed
var stub = new Order { Id = dto.Id, RowVersion = dto.RowVersion };
db.Attach(stub);
stub.Status = dto.Status;              // only Status marked Modified
await db.SaveChangesAsync(ct);

Cost model: snapshot change tracking is O(tracked entities) per DetectChanges, and DetectChanges runs automatically on SaveChanges, Entry(), Local and some queries. Loading 50,000 tracked rows to change one field is the classic slow import. For batch jobs call ChangeTracker.Clear() between batches, or use ExecuteUpdate.

No-tracking queries

// Read-only endpoint: no snapshots, no identity map
var list = await db.Products.AsNoTracking()
    .Where(p => p.CategoryId == categoryId)
    .ToListAsync(ct);

// Even better for APIs: project to a DTO (implicitly untracked, selects only needed columns)
var dtos = await db.Products
    .Where(p => p.CategoryId == categoryId)
    .Select(p => new ProductDto(p.Id, p.Name, p.Price))
    .ToListAsync(ct);

// No tracking but keep identity resolution (same row -> same instance in the graph)
var graph = await db.Orders.AsNoTrackingWithIdentityResolution()
    .Include(o => o.Lines).ThenInclude(l => l.Product)
    .ToListAsync(ct);

You can make no-tracking the default for a read-heavy context with optionsBuilder.UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking) and opt back in with AsTracking() where you intend to update. Beware: with plain AsNoTracking, the same customer appearing on 1,000 orders is materialized 1,000 times.

DbContext pooling

builder.Services.AddDbContextPool<ShopDbContext>(o =>
    o.UseSqlServer(builder.Configuration.GetConnectionString("Shop")),
    poolSize: 1024);   // default 1024; this is NOT the DB connection pool size

Pooling keeps context instances and their internal service graph around; on return the context is reset (change tracker cleared, state restored). Benchmarks show measurable gains for very high request rates, small or none for typical CRUD where the database dominates. Constraints: options are fixed at registration (no per-request OnConfiguring logic), you must not keep per-request state in custom context fields (it would leak across requests), and constructor-injected scoped services aren't possible. For multi-tenant connection strings use a pooled factory and set the connection per lease.

Don't confuse it with ADO.NET connection pooling, which is on by default and keyed by connection string (SqlClient Max Pool Size defaults to 100). Connection pool exhaustion usually comes from long-lived contexts or transactions, or thread-pool starvation, not from the context pool.

What it looks like

// With lazy-loading proxies enabled: 1 query for orders + 1 per order for Lines + 1 per line for Product
var orders = await db.Orders.Where(o => o.CustomerId == id).ToListAsync(ct);
foreach (var o in orders)
    total += o.Lines.Sum(l => l.Quantity * l.Product.Price);   // each navigation access = round trip

// Without lazy loading it shows up as "query in a loop"
foreach (var o in orders)
    o.Lines = await db.OrderLines.Where(l => l.OrderId == o.Id).ToListAsync(ct);

With 50 orders of 10 lines that's 1 + 50 + 500 round trips. Each is fast in isolation (2 ms), which is why it passes local tests and fails in production when latency to the database is higher, and the connection pool is held longer.

sequenceDiagram
  participant A as API
  participant D as Database
  A->>D: SELECT orders for customer
  D-->>A: 50 rows
  loop For each order
    A->>D: SELECT lines WHERE OrderId = x
    D-->>A: rows
  end
  Note over A,D: 51 round trips instead of 1 or 2

The loading strategies

Projections: the best fix for reads

var result = await db.Orders
    .Where(o => o.CustomerId == customerId)
    .OrderByDescending(o => o.CreatedAt)
    .Select(o => new OrderSummaryDto(
        o.Id,
        o.CreatedAt,
        o.Lines.Count,
        o.Lines.Sum(l => l.Quantity * l.UnitPrice),
        o.Lines.Select(l => new LineDto(l.Product.Name, l.Quantity)).ToList()))
    .ToListAsync(ct);

EF translates navigation access inside the projection into JOINs and correlated subqueries, selects only the needed columns, and the result is untracked. Aggregates (Count, Sum) are computed by the database. This is typically both the fastest and the least memory-hungry option.

Eager loading, cartesian explosion and split queries

var order = await db.Orders
    .Include(o => o.Lines.Where(l => !l.IsCancelled))   // filtered include
        .ThenInclude(l => l.Product)
    .Include(o => o.Payments)
    .Include(o => o.Shipments)
    .AsSplitQuery()
    .SingleAsync(o => o.Id == id, ct);

A single query with several collection includes JOINs them all: 1 order × 20 lines × 5 payments × 4 shipments = 400 rows, with order columns duplicated in each. That's cartesian explosion. EF logs a warning (MultipleCollectionIncludeWarning) when it detects multiple collection includes without a splitting behavior configured. AsSplitQuery() issues one query per collection (here four), each joined back to the root. Trade-offs:

• Split queries are more round trips, and without a transaction they're not a consistent snapshot (another writer can change data between them). Use snapshot/RCSI isolation or accept it.
• Split queries with Skip/Take need a deterministic, unique ordering; EF 10 fixed ordering consistency between the split queries, but you should still order by a unique key.
• Set a global default with UseSqlServer(cs, o => o.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery)) and override with AsSingleQuery().

Detecting N+1 systematically

• Logs: optionsBuilder.LogTo(Console.WriteLine, LogLevel.Information) in development or the Microsoft.EntityFrameworkCore.Database.Command category — repeated near-identical SQL is the fingerprint.
• Traces: with OpenTelemetry SQL instrumentation, an N+1 request looks like a comb of dozens of tiny DB spans under one HTTP span.
• Tests: an integration test with an interceptor (DbCommandInterceptor) that counts commands and asserts an upper bound for key endpoints prevents regressions.
• Make it impossible: don't enable lazy loading in web apps; with lazy loading off, a forgotten include yields empty collections/null navigations, which tests catch quickly. EF also throws if you lazy-load after the context is disposed.

Batching the "loop" case

When you genuinely must fetch related data for a list in a second step (e.g. from another bounded context), load it in one query with Contains and stitch in memory:

var ids = orders.Select(o => o.Id).ToArray();
var lines = await db.OrderLines.Where(l => ids.Contains(l.OrderId)).ToListAsync(ct);
var byOrder = lines.ToLookup(l => l.OrderId);

EF 10 translates ids.Contains into a padded list of scalar parameters by default (good plan caching and cardinality estimates); EF 8/9 used a JSON array parameter (OPENJSON). Watch very large lists — chunk them or use a table-valued parameter/temp table.

Bulk updates without loading entities

// Classic: load N rows, mutate, SaveChanges -> N UPDATE statements (batched) + N rows in memory
// Set-based: one statement, zero entities materialized
int archived = await db.Orders
    .Where(o => o.Status == OrderStatus.Completed && o.CompletedAt < cutoff)
    .ExecuteUpdateAsync(s => s
        .SetProperty(o => o.Status, OrderStatus.Archived)
        .SetProperty(o => o.ArchivedAt, DateTime.UtcNow), ct);

int purged = await db.AuditEntries
    .Where(a => a.CreatedAt < DateTime.UtcNow.AddYears(-7))
    .ExecuteDeleteAsync(ct);

// EF 10: setters can be a regular lambda, so conditional updates are trivial
await db.Products.Where(p => p.Id == cmd.Id)
    .ExecuteUpdateAsync(s =>
    {
        s.SetProperty(p => p.UpdatedAt, DateTime.UtcNow);
        if (cmd.Price is { } price) s.SetProperty(p => p.Price, price);
        if (cmd.Name is { } name)   s.SetProperty(p => p.Name, name);
    }, ct);

Before EF 10 the setter argument was an expression tree, so conditional setters required hand-building expressions. EF 10 also supports referencing JSON-mapped complex type properties inside ExecuteUpdate, generating efficient JSON modification SQL.

What you give up

That makes them perfect for maintenance jobs, soft-delete sweeps, counters (SetProperty(p => p.Views, p => p.Views + 1) is atomic in the database), and dangerous for aggregates whose invariants and events live in domain code. A common compromise: domain operations via tracked entities, bulk/administrative operations via Execute*, with auditing done in the database or explicitly.

// Optimistic concurrency with ExecuteUpdate: check the row count yourself
var rows = await db.Accounts
    .Where(a => a.Id == id && a.Version == expectedVersion)
    .ExecuteUpdateAsync(s => s
        .SetProperty(a => a.Balance, a => a.Balance - amount)
        .SetProperty(a => a.Version, a => a.Version + 1), ct);
if (rows == 0) throw new ConcurrencyConflictException(id);

Compiled queries

Every LINQ query execution normally computes a cache key from the expression tree and looks up the compiled query in EF's internal cache. That's cheap, but for queries executed tens of thousands of times per second it shows up in profiles. A compiled query does the translation once and gives you a delegate:

public sealed class ProductQueries
{
    private static readonly Func<ShopDbContext, int, CancellationToken, Task<ProductDto?>> ById =
        EF.CompileAsyncQuery((ShopDbContext db, int id, CancellationToken ct) =>
            db.Products.AsNoTracking()
              .Where(p => p.Id == id)
              .Select(p => new ProductDto(p.Id, p.Name, p.Price))
              .FirstOrDefault());

    public Task<ProductDto?> GetAsync(ShopDbContext db, int id, CancellationToken ct) => ById(db, id, ct);
}

Use them only after a profiler shows query compilation/caching overhead; the gains are in microseconds per call, not milliseconds. Limitations: parameters must be scalars or the context, the query shape is fixed (no conditional composition), and you can't append operators afterwards. EF 9 added experimental precompiled queries generated at publish time for Native AOT scenarios, which is a different feature.

A more common real-world win in the same area: avoid dynamic query shapes that defeat caching (e.g. building expressions with captured constants via Expression.Constant), and keep collection parameters parameterized.

Raw SQL safely

// Entity results, composable with LINQ (EF wraps it as a subquery)
var top = await db.Products
    .FromSql($"SELECT * FROM dbo.Products WITH (READPAST) WHERE CategoryId = {categoryId}")
    .Where(p => p.IsActive)
    .OrderBy(p => p.Name)
    .ToListAsync(ct);

// Unmapped / scalar results (EF 8+)
var stats = await db.Database
    .SqlQuery<CategoryStat>($"SELECT CategoryId, COUNT(*) AS Count FROM dbo.Products GROUP BY CategoryId")
    .ToListAsync(ct);

// Commands
await db.Database.ExecuteSqlAsync($"EXEC dbo.RebuildSearchIndex @since = {since}", ct);

// Raw: only for trusted fragments (identifiers from an allow-list); values still go in parameters
var col = allowedColumns[sortKey];   // e.g. "Name" or "Price" - never raw user text
var sql = "SELECT * FROM dbo.Products ORDER BY [" + col + "] OFFSET @skip ROWS";   // identifiers can't be parameters
var q = db.Products.FromSqlRaw(sql, new SqlParameter("@skip", skip));

FromSql, SqlQuery and ExecuteSql accept a FormattableString; each interpolation hole becomes a DbParameter, so injection is impossible through values. The Raw variants accept a plain string; concatenating user input there is SQL injection, and EF 10 ships an analyzer warning when it sees string concatenation in raw SQL calls. Identifiers (column/table names) can never be parameters — use an allow-list.

flowchart TD
  N["Need to touch many rows?"] -->|"yes, no domain logic"| X["ExecuteUpdate or ExecuteDelete"]
  N -->|"yes, with invariants and events"| B["Load in batches, SaveChanges, ChangeTracker.Clear"]
  N -->|"no"| L["LINQ query"]
  L -->|"LINQ cannot express it"| F["FromSql or SqlQuery with interpolation"]
  L -->|"profiler shows compile overhead"| C["EF.CompileAsyncQuery"]
  F -->|"dynamic identifiers"| R["FromSqlRaw with allow-list and parameters"]

Implicit transactions

SaveChangesAsync opens a connection, begins a transaction (unless one is already active), sends batched commands and commits. If any statement fails, everything in that call rolls back. Most request handlers need nothing more: build the change set in the tracker, call SaveChanges once.

Explicit transactions

await using var tx = await db.Database.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct);

var order = Order.Create(cmd.CustomerId, cmd.Lines);
db.Orders.Add(order);
await db.SaveChangesAsync(ct);                         // part 1

await db.Stock
    .Where(s => cmd.Skus.Contains(s.Sku))
    .ExecuteUpdateAsync(s => s.SetProperty(x => x.Reserved, x => x.Reserved + 1), ct);   // part 2

db.OutboxMessages.Add(OutboxMessage.From(new OrderPlaced(order.Id)));
await db.SaveChangesAsync(ct);                         // part 3

await tx.CommitAsync(ct);   // disposing without commit rolls back

Inside an explicit transaction, EF (5+) automatically creates a savepoint before each SaveChanges; if that save fails, EF rolls back to the savepoint, leaving earlier work intact so you can decide to fix and retry or abandon. You can manage savepoints yourself with CreateSavepointAsync/RollbackToSavepointAsync. To share one transaction with Dapper or ADO.NET, use db.Database.GetDbConnection() and tx.GetDbTransaction(); to join an external transaction, db.Database.UseTransactionAsync(dbTransaction).

TransactionScope also works (use TransactionScopeAsyncFlowOption.Enabled for async), but it's ambient and can escalate to distributed transactions if two connections enlist; explicit EF transactions are clearer.

Isolation levels in one table

Note that transactions alone don't stop lost updates under Read Committed; use concurrency tokens or atomic conditional updates for that.

Execution strategies: retrying transient failures

builder.Services.AddDbContext<ShopDbContext>(o =>
    o.UseSqlServer(cs, sql => sql.EnableRetryOnFailure(
        maxRetryCount: 5,
        maxRetryDelay: TimeSpan.FromSeconds(10),
        errorNumbersToAdd: null)));

Cloud databases have transient faults: failovers, throttling, dropped connections. The retrying execution strategy re-executes a failed operation with exponential backoff. For a single SaveChanges or query this is transparent. But it can't replay a transaction you started yourself — it doesn't know what your code did in between — so EF throws: "The configured execution strategy does not support user-initiated transactions." The fix is to give the strategy the whole unit of work as a delegate:

var strategy = db.Database.CreateExecutionStrategy();

await strategy.ExecuteAsync(async () =>
{
    db.ChangeTracker.Clear();   // the delegate may run more than once: start from a clean state

    await using var tx = await db.Database.BeginTransactionAsync(ct);
    var account = await db.Accounts.SingleAsync(a => a.Id == cmd.AccountId, ct);
    account.Withdraw(cmd.Amount);
    db.Ledger.Add(LedgerEntry.Debit(cmd.AccountId, cmd.Amount, cmd.IdempotencyKey));
    await db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);
});

flowchart TD
  S["strategy.ExecuteAsync"] --> B["Begin transaction"]
  B --> W["Reads and writes"]
  W --> C{"Commit ok?"}
  C -->|"yes"| D["Done"]
  C -->|"transient error"| R{"Retries left?"}
  W -->|"transient error"| R
  R -->|"yes, backoff"| S2["Clear tracker and rerun delegate"]
  S2 --> B
  R -->|"no"| F["Throw RetryLimitExceededException"]

The nasty edge case: a connection drop during commit — the commit may have succeeded on the server. Retrying would double-apply. Make the operation idempotent (unique idempotency key on the ledger row, so a duplicate insert fails cleanly), or use ExecuteInTransactionAsync with a verifySucceeded delegate that checks whether the commit landed.

Beyond one database

A transaction can't include publishing to Service Bus or calling a payment API. If you save then publish, a crash in between loses the message; if you publish then save, you may publish a lie. The standard answer is the transactional outbox: write the message to an outbox table in the same transaction as the business data, and have a background dispatcher publish it (at-least-once, so consumers must be idempotent). Distributed transactions (MSDTC/2PC) exist in .NET on Windows but are generally avoided in cloud architectures.

What each one actually gives you

The same query both ways

// EF Core: projection, untracked, parameterized
var orders = await db.Orders
    .Where(o => o.CustomerId == customerId && o.CreatedAt >= from)
    .OrderByDescending(o => o.CreatedAt)
    .Select(o => new OrderRow(o.Id, o.CreatedAt, o.Lines.Sum(l => l.Quantity * l.UnitPrice)))
    .Take(50)
    .ToListAsync(ct);

// Dapper: explicit SQL, you own the shape and the plan
const string sql = """
    SELECT TOP (50) o.Id, o.CreatedAt, SUM(l.Quantity * l.UnitPrice) AS Total
    FROM dbo.Orders o
    JOIN dbo.OrderLines l ON l.OrderId = o.Id
    WHERE o.CustomerId = @customerId AND o.CreatedAt >= @from
    GROUP BY o.Id, o.CreatedAt
    ORDER BY o.CreatedAt DESC
    """;
await using var conn = new SqlConnection(cs);
var rows = (await conn.QueryAsync<OrderRow>(
    new CommandDefinition(sql, new { customerId, from }, cancellationToken: ct))).AsList();

For this query the performance difference is negligible compared with network and database time. The real differences: EF generated SQL you should review for complex queries; Dapper's SQL is exactly what you wrote, including the bugs, and it won't notice when a column is renamed.

Performance, honestly

Benchmarks show Dapper ahead on raw materialization, but EF Core's gap has narrowed dramatically across versions; with AsNoTracking and projections, EF overhead is usually microseconds per query. Where EF genuinely costs more: tracked queries over many rows, complex LINQ translating to suboptimal SQL, very hot simple queries where translation-cache lookup matters, and large graphs with Include. Where Dapper wins clearly: hand-tuned SQL using database-specific features (window functions, CTEs, hints, MERGE, table-valued parameters), reporting/analytics, and bulk reads mapped to flat DTOs.

Using both in one application

// Reuse EF's connection and transaction for a Dapper query in the same unit of work
await using var tx = await db.Database.BeginTransactionAsync(ct);

db.Invoices.Add(invoice);
await db.SaveChangesAsync(ct);

var conn = db.Database.GetDbConnection();
var report = await conn.QueryAsync<AgingBucket>(new CommandDefinition(
    "SELECT * FROM dbo.fn_AgingReport(@customerId)",
    new { customerId = invoice.CustomerId },
    transaction: tx.GetDbTransaction(),
    cancellationToken: ct));

await tx.CommitAsync(ct);

flowchart LR
  C["Commands: create order, approve, cancel"] --> EF["EF Core: aggregates, tracking, SaveChanges"]
  Q1["Simple reads, APIs"] --> EFP["EF Core projections, no tracking"]
  Q2["Reports, dashboards, complex SQL"] --> DP["Dapper with hand-tuned SQL"]
  EF --> DB[("Database")]
  EFP --> DB
  DP --> DB

This maps naturally to CQRS-style separation: the write side benefits from EF's unit of work and invariants; the read side can use whatever is fastest for each screen. Keep schema ownership in one place (EF migrations) so Dapper queries break in CI, not production — integration tests against a real database (Testcontainers) are mandatory for raw SQL.

Decision guide

• Choose EF Core for line-of-business apps with rich domain models, many entities, frequent schema evolution, teams that prefer C# over SQL, and when you want migrations and global filters (multi-tenancy, soft delete).
• Choose Dapper for read-heavy services with stable schemas, DBA-owned schemas or stored procedures, reporting, or legacy databases whose structure doesn't fit an ORM model.
• Before switching to Dapper for speed, measure: check the SQL EF generates, add projections/AsNoTracking, fix N+1, consider SqlQuery<T> or FromSql. Most "EF is slow" cases are query-shape problems.

What to test at which level

For web APIs the in-process integration test gives the best value per minute: it exercises nearly everything that breaks in production but runs in hundreds of milliseconds per test with a shared container.

WebApplicationFactory + Testcontainers

// Packages: Microsoft.AspNetCore.Mvc.Testing, Testcontainers.PostgreSql, Respawn, xunit.v3
public sealed class ApiFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    private readonly PostgreSqlContainer _db = new PostgreSqlBuilder("postgres:17-alpine").Build();
    private Respawner _respawner = default!;

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.UseEnvironment("Testing");
        builder.UseSetting("ConnectionStrings:Shop", _db.GetConnectionString());   // real DB, same code path

        builder.ConfigureTestServices(services =>
        {
            services.RemoveAll<IPaymentGateway>();
            services.AddSingleton<IPaymentGateway, FakePaymentGateway>();     // external boundary only

            services.AddAuthentication(TestAuthHandler.Scheme)
                    .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>(TestAuthHandler.Scheme, _ => { });
        });
    }

    public async ValueTask InitializeAsync()
    {
        await _db.StartAsync();
        using var scope = Services.CreateScope();
        await scope.ServiceProvider.GetRequiredService<ShopDbContext>().Database.MigrateAsync();
        await using var conn = new NpgsqlConnection(_db.GetConnectionString());
        await conn.OpenAsync();
        _respawner = await Respawner.CreateAsync(conn, new RespawnerOptions { DbAdapter = DbAdapter.Postgres });
    }

    public async Task ResetDatabaseAsync()
    {
        await using var conn = new NpgsqlConnection(_db.GetConnectionString());
        await conn.OpenAsync();
        await _respawner.ResetAsync(conn);
    }

    public override async ValueTask DisposeAsync()
    {
        await _db.DisposeAsync();
        await base.DisposeAsync();
    }
}

public sealed class OrdersApiTests(ApiFactory factory) : IClassFixture<ApiFactory>, IAsyncLifetime
{
    public ValueTask InitializeAsync() => new(factory.ResetDatabaseAsync());
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;

    [Fact]
    public async Task Create_order_returns_201_and_persists()
    {
        var client = factory.CreateClient();
        var ct = TestContext.Current.CancellationToken;

        var response = await client.PostAsJsonAsync("/orders",
            new { customerId = 42, lines = new[] { new { sku = "ABC", quantity = 2 } } }, ct);

        Assert.Equal(HttpStatusCode.Created, response.StatusCode);
        var created = await response.Content.ReadFromJsonAsync<OrderDto>(ct);
        Assert.NotNull(response.Headers.Location);

        var get = await client.GetFromJsonAsync<OrderDto>(response.Headers.Location, ct);
        Assert.Equal(created!.Id, get!.Id);
    }

    [Fact]
    public async Task Invalid_order_returns_problem_details()
    {
        var client = factory.CreateClient();
        var response = await client.PostAsJsonAsync("/orders", new { customerId = 0 },
            TestContext.Current.CancellationToken);
        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
        Assert.Equal("application/problem+json", response.Content.Headers.ContentType?.MediaType);
    }
}

In .NET 10 you no longer need public partial class Program {}: a source generator makes the top-level-statements Program class public so WebApplicationFactory<Program> works out of the box. Overriding the connection string via UseSetting keeps the production AddDbContext registration intact — simpler and safer than removing and re-adding DbContext options.

flowchart LR
  T["xUnit test"] -->|"HttpClient"| TS["TestServer in memory"]
  TS --> P["Real middleware pipeline, DI, auth, validation"]
  P --> E["Endpoints and EF Core"]
  E --> PG[("PostgreSQL in Testcontainers")]
  P --> F["Fake payment gateway"]
  R["Respawn reset between tests"] -.-> PG

Why not the EF in-memory provider or SQLite in-memory?

The in-memory provider isn't relational: no SQL, no constraints, no transactions, different null and case semantics, and LINQ that would fail translation on SQL Server runs fine in memory. Microsoft explicitly recommends against it for testing. SQLite is relational but a different dialect (no rowversion, different collations, limited ALTER). Testing against the same engine as production catches migrations, constraints, concurrency tokens and query-translation problems. Container start cost (a few seconds) is paid once per fixture/collection.

Mocking: where it belongs

• Mock at boundaries you don't own: payment providers, email/SMS, third-party APIs. Prefer a fake implementation of your port interface, or stub HTTP with a custom HttpMessageHandler / WireMock.Net so typed-client serialization is exercised too.
• Don't mock DbContext, IQueryable or HttpContext internals — you end up testing your mocks. Use the real thing in an integration test.
• Time: inject TimeProvider (.NET 8+) and use FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) for expiry and scheduling logic.
• Auth: a test authentication handler that issues a principal with configurable claims beats disabling authorization; you still test policies.
• Logs: FakeLogger from Microsoft.Extensions.Diagnostics.Testing lets you assert on structured log output.

Keeping the suite fast and reliable

• Share one container per test collection; reset data with Respawn or transactions rolled back per test, not a new container per test.
• Background services: disable or replace hosted services that poll queues so tests are deterministic.
• Parallelism: separate databases (or schemas) per collection if tests run in parallel.
• CI: Testcontainers needs a Docker-compatible runtime on the agent (GitHub-hosted Ubuntu runners have it).
• .NET 10's dotnet test supports Microsoft.Testing.Platform natively (opt in through global.json), and xUnit v3 runs on it.

The problem

A typical system has an API, a worker, a React frontend, PostgreSQL, Redis and a message broker. Without Aspire, local development means a docker-compose file that drifts from reality, hard-coded localhost:5432 strings in appsettings.Development.json, a README listing startup order, five terminals, and no unified view of logs or traces. Each service configures telemetry and retries differently. Aspire replaces that with one strongly typed model and consistent defaults.

The AppHost

// AppHost project: Sdk="Aspire.AppHost.Sdk/13.x", references service projects
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("pg").WithDataVolume().WithPgAdmin();
var ordersDb = postgres.AddDatabase("orders");
var cache = builder.AddRedis("cache");
var bus = builder.AddRabbitMQ("bus");

var migrator = builder.AddProject<Projects.Shop_Migrator>("migrator")
    .WithReference(ordersDb).WaitFor(ordersDb);

var api = builder.AddProject<Projects.Shop_Api>("api")
    .WithReference(ordersDb)
    .WithReference(cache)
    .WithReference(bus)
    .WaitForCompletion(migrator)
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.Shop_Worker>("worker")
    .WithReference(bus).WithReference(ordersDb)
    .WaitFor(bus);

builder.AddViteApp("web", "../shop-web")          // Aspire.Hosting.JavaScript
    .WithReference(api)
    .WithExternalHttpEndpoints();

builder.Build().Run();

What happens on aspire run (or F5): containers start, projects launch with environment variables like ConnectionStrings__orders and services__api__https__0, resources wait for dependencies' health, and the dashboard shows resource state, console logs, structured logs, traces and metrics for everything — including the Python or JavaScript parts.

flowchart LR
  AH["AppHost C# model"] -->|"starts and wires"| API["Shop.Api"]
  AH --> W["Shop.Worker"]
  AH --> WEB["Vite React app"]
  AH --> PG[("Postgres container")]
  AH --> RD[("Redis container")]
  AH --> MQ{{"RabbitMQ container"}}
  API -->|"OTLP"| D["Aspire dashboard"]
  W -->|"OTLP"| D
  WEB -->|"service discovery"| API
  AH -->|"publish or deploy"| T["ACA, Kubernetes, Compose manifests"]

ServiceDefaults and client integrations

// Shop.Api/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();                       // OTel logs/traces/metrics + OTLP, health checks,
                                                    // service discovery, standard HTTP resilience
builder.AddNpgsqlDbContext<OrdersDbContext>("orders");   // Aspire.Npgsql.EntityFrameworkCore.PostgreSQL
builder.AddRedisDistributedCache("cache");
builder.AddRabbitMQClient("bus");

builder.Services.AddHttpClient<CatalogClient>(c =>
    c.BaseAddress = new Uri("https+http://catalog"));   // resolved by service discovery

var app = builder.Build();
app.MapDefaultEndpoints();                          // /health and /alive (dev by default)
app.Run();

Client integrations (Aspire.* packages) read the injected connection string by resource name and also register health checks, telemetry and sensible retries for that client. They're ordinary NuGet packages: the service still runs without the AppHost if you supply configuration the normal way, which keeps services deployable anywhere.

Service discovery (Microsoft.Extensions.ServiceDiscovery) resolves logical names like http://catalog from configuration (services:catalog:https:0), which the AppHost injects locally and deployment targets provide in production (e.g. Container Apps internal DNS, Kubernetes services). The https+http:// scheme means "prefer HTTPS, fall back to HTTP".

From dev to deployment

• aspire publish / aspire deploy and the aspire do pipeline (Aspire 13) generate artifacts or deploy the model; compute environments such as Azure Container Apps, Docker Compose and Kubernetes are added to the model. The Azure Developer CLI (azd) also understands the model for provisioning.
• Azure resources can be modelled (AddAzureServiceBus, AddAzurePostgresFlexibleServer…) with emulators or containers locally (RunAsEmulator, RunAsContainer).
• For complex production infrastructure many teams keep Bicep/Terraform as the source of truth and use Aspire mainly for the inner loop plus ServiceDefaults — a perfectly valid adoption level.

What it is and isn't

Testing benefits too: Aspire.Hosting.Testing spins up the AppHost for end-to-end tests with real containers.

Multi-stage Dockerfile

# syntax=docker/dockerfile:1
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

# 1. Restore with only project files copied -> cached layer until dependencies change
COPY Directory.Packages.props Directory.Build.props ./
COPY src/Shop.Api/Shop.Api.csproj src/Shop.Api/
COPY src/Shop.Domain/Shop.Domain.csproj src/Shop.Domain/
RUN dotnet restore src/Shop.Api/Shop.Api.csproj

# 2. Copy the rest and publish
COPY . .
RUN dotnet publish src/Shop.Api/Shop.Api.csproj -c Release -o /app --no-restore /p:UseAppHost=false

# 3. Minimal runtime image
FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled AS final
WORKDIR /app
COPY --from=build /app .
USER $APP_UID
EXPOSE 8080
ENTRYPOINT ["dotnet", "Shop.Api.dll"]

Why each part matters: copying project files first maximizes layer caching (restore is the slow step); a .dockerignore excluding bin/, obj/, .git and secrets keeps the context small and safe; the final stage contains only the published output, not the SDK, source or NuGet cache. $APP_UID is an environment variable defined in the .NET images for the non-root user. The exec-form ENTRYPOINT makes dotnet PID 1 so it receives SIGTERM for graceful shutdown (chiseled images have no shell anyway).

No Dockerfile: SDK container publish

<PropertyGroup>
  <ContainerRepository>contoso/shop-api</ContainerRepository>
  <ContainerFamily>noble-chiseled</ContainerFamily>
  <ContainerImageTags>1.4.2;latest</ContainerImageTags>
</PropertyGroup>
<ItemGroup>
  <ContainerLabel Include="org.opencontainers.image.source" Value="https://github.com/contoso/shop" />
</ItemGroup>

dotnet publish src/Shop.Api -c Release -t:PublishContainer \
  -p:ContainerRegistry=contoso.azurecr.io --os linux --arch x64

The SDK picks the right base image (aspnet vs runtime vs runtime-deps for self-contained/AOT), sets the non-root user and port, and pushes directly to a registry or the local Docker daemon — no Docker needed for building. It doesn't run arbitrary build steps (no RUN apt-get), so if you need extra OS packages you use a custom base image (ContainerBaseImage). In .NET 10 console apps can use PublishContainer without opting in, and ContainerImageFormat lets you force Docker or OCI manifests.

Choosing a base image

Chiseled images default to invariant globalization; if you format dates/currencies per culture or convert time zones, use the -extra variant or you'll see culture-insensitive output or TimeZoneNotFoundException.

Runtime behavior inside containers

• Ports: ASPNETCORE_HTTP_PORTS=8080 by default since .NET 8 (non-root can't bind 80).
• Memory: the GC respects cgroup limits; with a memory limit set, the default heap hard limit is 75% of it. Set Kubernetes limits; consider DOTNET_GCHeapHardLimitPercent if native memory is significant. Server GC with DATAS (default since .NET 9) adapts heap count to load, which helps density.
• CPU: the runtime reads the CPU quota for Environment.ProcessorCount, affecting thread pool and GC heaps; fractional limits like 0.5 CPU hurt latency.
• Shutdown: SIGTERM triggers the generic host's graceful shutdown (30 s default timeout); align terminationGracePeriodSeconds.
• Read-only root filesystem: works with chiseled images; mount writable volumes for temp files, and persist Data Protection keys externally.
• Diagnostics: no shell means no exec debugging; use dotnet-monitor as a sidecar or ephemeral debug containers.

flowchart LR
  SRC["Source and csproj"] --> B1["Stage build: sdk 10.0, restore, publish"]
  B1 -->|"COPY --from=build"| F["Stage final: aspnet 10.0 noble chiseled"]
  F --> R[("Registry ACR or GHCR")]
  R --> K["Kubernetes or Container Apps, non-root, read-only FS"]
  SC["Image scanning and SBOM"] -.-> R

Supply chain hygiene

• Pin base images by version tag (and digest for reproducibility); rebuild regularly to pick up patched layers — Microsoft refreshes images on Patch Tuesday.
• Scan images (Defender for Cloud, Trivy, Grype) and generate an SBOM; chiseled images dramatically reduce findings.
• Never bake secrets into layers or build args; use BuildKit secrets for private feeds during restore and platform secrets at runtime.
• Sign images and enforce policies (only signed images from your registry) in the cluster.

Central Package Management

<!-- Directory.Packages.props at the repo root -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.0" />
    <PackageVersion Include="Polly.Core" Version="8.6.4" />
    <PackageVersion Include="xunit.v3" Version="3.1.0" />
    <!-- pin a vulnerable transitive dependency to a patched version -->
    <PackageVersion Include="System.Text.RegularExpressions" Version="4.3.1" />
  </ItemGroup>
  <ItemGroup>
    <!-- applies to every project: analyzers and other build-only tools -->
    <GlobalPackageReference Include="Meziantou.Analyzer" Version="2.0.250" />
  </ItemGroup>
</Project>

<!-- In a project: no Version attribute -->
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" />

Benefits: one PR upgrades a package everywhere, no "project A on 8.0.1, project B on 8.0.11" conflicts, and Renovate/Dependabot update a single file. Transitive pinning lets you raise a transitive dependency's version centrally (e.g. to patch a CVE) without adding direct references to every project. VersionOverride exists for a justified exception in one project — use sparingly. (The version numbers above are illustrative.)

Lock files and reproducible restores

<!-- Directory.Build.props -->
<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode Condition="'$(CI)' == 'true'">true</RestoreLockedMode>
</PropertyGroup>

Floating versions (10.*) and version ranges resolve to "whatever is newest at restore time", and even exact direct references can pull different transitive versions when a new package is published. A committed packages.lock.json records the exact resolved graph with content hashes; in CI, dotnet restore --locked-mode fails if the graph would change, so builds are reproducible and tamper-evident. Developers regenerate the lock file intentionally when changing dependencies.

Vulnerability auditing

<PropertyGroup>
  <NuGetAudit>true</NuGetAudit>
  <NuGetAuditMode>all</NuGetAuditMode>
  <NuGetAuditLevel>moderate</NuGetAuditLevel>
  <!-- fail builds on high/critical, keep low/moderate as warnings -->
  <WarningsAsErrors>$(WarningsAsErrors);NU1903;NU1904</WarningsAsErrors>
</PropertyGroup>
<ItemGroup>
  <!-- documented, reviewed exception -->
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-xxxx-xxxx-xxxx" />
</ItemGroup>

dotnet package list --vulnerable --include-transitive
dotnet package update --vulnerable          # .NET 10 SDK: bump to the lowest non-vulnerable versions

Warnings NU1901–NU1904 map to low/moderate/high/critical. Package pruning in .NET 10 removes references to packages already provided by the shared framework (e.g. old System.* packages), which cuts false positives; you may see NU1510 telling you a direct reference is unnecessary.

Supply-chain defences beyond CVEs

<!-- nuget.config: package source mapping prevents dependency confusion -->
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/internal/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="contoso"><package pattern="Contoso.*" /></packageSource>
    <packageSource key="nuget.org"><package pattern="*" /></packageSource>
  </packageSourceMapping>
</configuration>

Without mapping, an attacker who publishes Contoso.Billing 99.0.0 on nuget.org could win version resolution over your internal feed. Also: reserve your ID prefix on nuget.org, require signed packages if your policy demands (trustedSigners), and prefer an upstreaming internal feed (Azure Artifacts, GitHub Packages) so you control what enters the build.

SourceLink and debuggable packages

<PropertyGroup>
  <ContinuousIntegrationBuild Condition="'$(CI)' == 'true'">true</ContinuousIntegrationBuild>  <!-- deterministic paths -->
  <PublishRepositoryUrl>true</PublishRepositoryUrl>
  <EmbedUntrackedSources>true</EmbedUntrackedSources>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

SourceLink writes a mapping from file paths to raw URLs at a specific commit into the PDB. When a consumer debugs into your package (or reads a crash dump), the debugger downloads the exact source. Since the .NET 8 SDK, SourceLink support for GitHub, Azure Repos, GitLab and Bitbucket is built in — no extra package needed. Publishing .snupkg symbol packages to nuget.org's symbol server completes the picture.

flowchart LR
  D["Developer adds PackageReference"] --> CPM["Directory.Packages.props version"]
  CPM --> R["dotnet restore"]
  NC["nuget.config source mapping"] --> R
  R --> A{"NuGet Audit: known CVE?"}
  A -->|"high or critical"| X["Build fails NU1903 or NU1904"]
  A -->|"clean"| L["packages.lock.json verified in locked mode"]
  L --> B["Build with SourceLink and deterministic output"]