Use minimal APIs for new .NET 10 APIs, and keep controllers when you need MVC-only features like custom model binders or OData. In my local benchmarks of one orders API, the minimal endpoint was faster in 5 of 6 runs, by up to 1.57x.

Minimal APIs vs Controllers at a Glance

Every row comes from the same project, tested on .NET 10 (SDK 10.0.402) further down:

Microsoft’s own guidance now says to start new projects with minimal APIs. If you’re still on .NET 8, upgrade to .NET 10 first: the validation support below needs it.

The Sample: One US Orders API Built Both Ways

I put both styles in one project, UsOrdersApi, so they share the same store, middleware and server. /minimal/orders is the minimal API and /controllers/orders is the controller. The only package is Microsoft.AspNetCore.OpenApi 10.0.14:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.14" />
  </ItemGroup>

</Project>

The models are positional records (here’s when a record beats a class), and CreateOrder carries the validation attributes. Three Texas and California orders seed the store:

using System.ComponentModel.DataAnnotations;

namespace UsOrdersApi;

public record Order(int Id, string Customer, string State, decimal Total);

public record CreateOrder(
    [Required] string Customer,
    [Required, StringLength(2, MinimumLength = 2)] string State,
    [Range(1, 10_000)] decimal Total);

// One in-memory store, shared by both styles (registered as a singleton)
public class OrderStore
{
    readonly List<Order> orders =
    [
        new(1, "Jenna Morales", "TX", 249.99m),
        new(2, "Tyler Brooks", "CA", 89.50m),
        new(3, "Rachel Kim", "TX", 1200.00m),
    ];

    public IEnumerable<Order> All(string? state) =>
        state is null ? orders : orders.Where(o => o.State == state);

    public Order? Find(int id) => orders.FirstOrDefault(o => o.Id == id);

    public Order Add(CreateOrder input)
    {
        lock (orders)
        {
            var order = new Order(orders.Count + 1, input.Customer, input.State, input.Total);
            orders.Add(order);
            return order;
        }
    }
}

Program.cs registers both styles side by side. Yes, one app can serve minimal endpoints and controllers at the same time:

using UsOrdersApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<OrderStore>();
builder.Services.AddControllers();   // controllers
builder.Services.AddValidation();    // .NET 10 validation for minimal APIs
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
app.MapControllers();                // OrdersController
app.MapOrderEndpoints();             // OrderEndpoints (MapGroup)

app.Run();

The launch profile pins port 5793, and appsettings.json is the template’s logging config:

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5793",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

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

Routing: Minimal API MapGroup vs Controller [Route]

The minimal side lives in OrderEndpoints.cs. MapGroup sets the prefix, the OpenAPI tag and the filter once for every endpoint in the group:

using Microsoft.AspNetCore.Http.HttpResults;

namespace UsOrdersApi;

public static class OrderEndpoints
{
    public static RouteGroupBuilder MapOrderEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/minimal/orders")
            .WithTags("Minimal")
            .AddEndpointFilter<StyleHeaderFilter>();

        group.MapGet("/", (string? state, OrderStore store) => store.All(state));
        group.MapGet("/{id:int}", GetById);
        group.MapPost("/", Create);
        return group;
    }

    public static Results<Ok<Order>, NotFound> GetById(int id, OrderStore store) =>
        store.Find(id) is { } order ? TypedResults.Ok(order) : TypedResults.NotFound();

    public static Created<Order> Create(CreateOrder input, OrderStore store)
    {
        var order = store.Add(input);
        return TypedResults.Created($"/minimal/orders/{order.Id}", order);
    }
}

The controller gets the same thing from attributes: [Route] on the class, [HttpGet] and [HttpPost] on the actions:

using Microsoft.AspNetCore.Mvc;

namespace UsOrdersApi.Controllers;

[ApiController]
[Route("controllers/orders")]
[StyleHeader]
public class OrdersController(OrderStore store) : ControllerBase
{
    [HttpGet]
    public IEnumerable<Order> GetAll(string? state) => store.All(state);

    [HttpGet("{id:int}")]
    public ActionResult<Order> GetById(int id) =>
        store.Find(id) is { } order ? order : NotFound();

    [HttpPost]
    public ActionResult<Order> Create([FromBody] CreateOrder input)
    {
        var order = store.Add(input);
        return CreatedAtAction(nameof(GetById), new { id = order.Id }, order);
    }
}

Same store, same query. Here’s Texas orders from both:

curl.exe -i "http://localhost:5793/minimal/orders?state=TX"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Api-Style: minimal (endpoint filter)
[{"id":1,"customer":"Jenna Morales","state":"TX","total":249.99},{"id":3,"customer":"Rachel Kim","state":"TX","total":1200.00}]

curl.exe -i "http://localhost:5793/controllers/orders?state=TX"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Api-Style: controller (action filter)
[{"id":1,"customer":"Jenna Morales","state":"TX","total":249.99},{"id":3,"customer":"Rachel Kim","state":"TX","total":1200.00}]

Both returned the same two orders, Jenna Morales ($249.99) and Rachel Kim ($1,200.00). The bodies match byte for byte; only my style header differs.

Route constraints like {id:int} work the same in both. Under the hood, both use endpoint routing, so ASP.NET Core middleware runs the same way for either style.

Model Binding: Do Minimal APIs Need [FromBody]?

No. A minimal API binds a complex type like CreateOrder from the JSON body on its own, and simple types like string? state from the route or query string. [ApiController] applies the same rules to controllers, so [FromBody] there is just documentation.

Posting a valid Florida order to both:

curl.exe -i -X POST http://localhost:5793/minimal/orders -H "Content-Type: application/json" -d '{"customer":"Marcus Reed","state":"FL","total":74.25}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /minimal/orders/4
X-Api-Style: minimal (endpoint filter)
{"id":4,"customer":"Marcus Reed","state":"FL","total":74.25}

curl.exe -i -X POST http://localhost:5793/controllers/orders -H "Content-Type: application/json" -d '{"customer":"Marcus Reed","state":"FL","total":74.25}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: http://localhost:5793/controllers/orders/5
X-Api-Style: controller (action filter)
{"id":5,"customer":"Marcus Reed","state":"FL","total":74.25}

Both returned 201 Created. The Location header differs, though: TypedResults.Created sent my relative /minimal/orders/4, while CreatedAtAction built the absolute http://localhost:5793/controllers/orders/5 from the route.

Validation: AddValidation in .NET 10 vs [ApiController] ModelState

Controllers have validated automatically for years: [ApiController] checks ModelState and returns a 400 before the action runs. Minimal APIs got the same thing in .NET 10 with builder.Services.AddValidation(), which uses a source generator to find the endpoint parameter types.

Same bad order to both (blank customer, “Texas” as the state, a $0 total):

curl.exe -i -X POST http://localhost:5793/minimal/orders -H "Content-Type: application/json" -d '{"customer":"","state":"Texas","total":0}'
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{"title":"One or more validation errors occurred.","errors":{"Customer":["The Customer field is required."],"State":["The field State must be a string with a minimum length of 2 and a maximum length of 2."],"Total":["The field Total must be between 1 and 10000."]}}

curl.exe -i -X POST http://localhost:5793/controllers/orders -H "Content-Type: application/json" -d '{"customer":"","state":"Texas","total":0}'
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"One or more validation errors occurred.","status":400,"errors":{"State":["The field State must be a string with a minimum length of 2 and a maximum length of 2."],"Total":["The field Total must be between 1 and 10000."],"Customer":["The Customer field is required."]},"traceId":"00-…-00"}

Both caught all three errors with the same messages. The shape differs: the minimal API sent plain application/json with only title and errors, while the controller sent application/problem+json with type, status and traceId.

To get the controller’s shape, I added builder.Services.AddProblemDetails(); and posted the same order again:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"One or more validation errors occurred.","status":400,"errors":{"Customer":["The Customer field is required."],"State":["The field State must be a string with a minimum length of 2 and a maximum length of 2."],"Total":["The field Total must be between 1 and 10000."]},"traceId":"00-…-00"}

Note: skip AddValidation() and nothing fails loudly. Invalid orders just reach your handler. On .NET 10, nullable value type parameters (like int?) also aren’t validated yet.

Filters: Minimal API IEndpointFilter vs Controller Action Filters

Both styles let you run code around the handler. Minimal APIs use IEndpointFilter; controllers use MVC’s filter pipeline. Mine both set an X-Api-Style header:

using Microsoft.AspNetCore.Mvc.Filters;

namespace UsOrdersApi;

// Minimal APIs: endpoint filter, runs around the handler
public class StyleHeaderFilter : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        context.HttpContext.Response.Headers["X-Api-Style"] = "minimal (endpoint filter)";
        return await next(context);
    }
}

// Controllers: action filter, runs around the action method
public class StyleHeaderAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext context) =>
        context.HttpContext.Response.Headers["X-Api-Style"] = "controller (action filter)";
}

You saw them work in the curl output: every 200 and 201 carried the header. The 400s didn’t, in either style, because validation short-circuited the request before my filter ran.

Controllers still have more filter types (resource, result, exception, authorization). For minimal APIs, I put cross-cutting work like error handling and auth in middleware or on the group with RequireAuthorization(), which pairs well with JWT bearer authentication.

Dependency Injection in Minimal API Handlers vs Controllers

Look back at the two files. The minimal handler takes OrderStore store as a parameter, and ASP.NET Core sees it’s a registered service. The controller takes it through a primary constructor, and a new controller is created for every request.

The lifetimes work the same either way, so OrderStore is one singleton shared by both styles. My guide to transient, scoped and singleton lifetimes covers which one to pick.

One practical difference: a controller with ten actions builds every dependency for every request, even ones only one action needs. A minimal handler asks only for what it uses.

OpenAPI Support for Minimal APIs and Controllers

Both styles feed the built-in AddOpenApi() document. This file-based app reads /openapi/v1.json and lists each operation with its tag and response codes:

using System.Text.Json;

var http = new HttpClient();
var url = "http://localhost:5793/openapi/v1.json";
using var doc = JsonDocument.Parse(await http.GetStringAsync(url));

foreach (var path in doc.RootElement.GetProperty("paths").EnumerateObject())
    foreach (var op in path.Value.EnumerateObject())
    {
        var tag = op.Value.GetProperty("tags")[0].GetString();
        var codes = string.Join(",", op.Value.GetProperty("responses")
            .EnumerateObject().Select(r => r.Name));
        Console.WriteLine(
            $"{op.Name.ToUpper(),-5} {path.Name,-26} {tag,-8} {codes}");
    }

Output:

GET   /minimal/orders            Minimal  200
POST  /minimal/orders            Minimal  201
GET   /minimal/orders/{id}       Minimal  200,404
GET   /controllers/orders        Orders   200
POST  /controllers/orders        Orders   200
GET   /controllers/orders/{id}   Orders   200

The minimal GetById returns Results<Ok<Order>, NotFound>, so OpenAPI knows both codes. The controller’s ActionResult<Order> only documents 200 until you add [ProducesResponseType(StatusCodes.Status404NotFound)].

The POST rows tell the same story: the minimal Created<Order> documents 201, while the controller claims 200 even though it really returns 201. Neither side lists the validation 400 on its own.

To browse that document in a UI, follow my OpenAPI with Scalar setup; it works the same for both styles.

Testing Minimal API Handlers vs Controller Actions

Unit tests are where named handlers pay off. This file-based app references the project with #:project and calls both styles directly, no server involved:

#:project UsOrdersApi/UsOrdersApi.csproj
using Microsoft.AspNetCore.Http.HttpResults;
using UsOrdersApi;
using UsOrdersApi.Controllers;

var store = new OrderStore();

// Minimal API: the handler is a plain static method
var found = OrderEndpoints.GetById(1, store).Result;
var missing = OrderEndpoints.GetById(99, store).Result;
if (found is Ok<Order> ok) Console.WriteLine($"Minimal 1:     Ok, {ok.Value!.Customer}");
if (missing is NotFound) Console.WriteLine("Minimal 99:    NotFound");

// Controller: create it with its dependencies, then call the action
var ctrl = new OrdersController(store);
Console.WriteLine($"Controller 1:  {ctrl.GetById(1).Value!.Customer}");
var notFound = ctrl.GetById(99).Result!;
Console.WriteLine($"Controller 99: {notFound.GetType().Name}");

Output:

Minimal 1:     Ok, Jenna Morales
Minimal 99:    NotFound
Controller 1:  Jenna Morales
Controller 99: NotFoundResult

The minimal handler is a static method, so the test passes in the store and pattern-matches Ok<Order> or NotFound. The controller works too, but you build it first and inspect Value or Result (NotFoundResult).

For integration tests, WebApplicationFactory from Microsoft.AspNetCore.Mvc.Testing hosts the whole app in memory and works the same for both. Your test client is just an HttpClient.

Minimal API Performance: Is It Faster Than Controllers?

Usually, yes. I ran this benchmark against the Release build of UsOrdersApi: 2,000 warm-up calls each, then three rounds of 20,000 GET /orders/1 requests at 32 concurrent, keeping each style’s best round:

using System.Diagnostics;
using System.Globalization;

CultureInfo.CurrentCulture = new CultureInfo("en-US");
var http = new HttpClient();
var api = "http://localhost:5793";
string[] urls = [$"{api}/minimal/orders/1", $"{api}/controllers/orders/1"];
foreach (var url in urls) await Run(url, 2_000);       // warm-up
var best = new double[2];
for (int round = 0; round < 3; round++)                // best of 3
    for (int i = 0; i < 2; i++)
        best[i] = Math.Max(best[i], await Run(urls[i], 20_000));
string[] lines = [$"Minimal API  {best[0],8:N0} req/s",
                  $"Controller   {best[1],8:N0} req/s",
                  $"Ratio        {best[0] / best[1],8:F2}x"];
foreach (var line in lines) Console.WriteLine(line);
File.WriteAllLines("bench-results.txt", lines);

async Task<double> Run(string url, int count)
{
    var sw = Stopwatch.StartNew();
    var opts = new ParallelOptions { MaxDegreeOfParallelism = 32 };
    await Parallel.ForAsync(0, count, opts, async (_, ct) =>
        (await http.GetAsync(url, ct)).EnsureSuccessStatusCode());
    return count / sw.Elapsed.TotalSeconds;
}

Output:

Minimal API    63,179 req/s
Controller     40,363 req/s
Ratio            1.57x

In the run you see, the minimal endpoint served 63,179 requests per second and the controller 40,363, a ratio of 1.57x. The client uses async and await with Parallel.ForAsync to keep 32 requests in flight.

Raw numbers swung a lot. Across 6 runs of this benchmark, minimal APIs came out ahead 5 times (1.29x to 1.57x), and the other run was within 2% either way, a tie.

Important: this is one laptop, with the client and server sharing CPU, on a tiny in-memory endpoint. A database call or real JSON payload costs far more than the framework gap, so don’t migrate a working API for speed alone.

Native AOT: Minimal APIs Only

Native AOT compiles the app to one self-contained executable with faster startup and less memory. Microsoft’s compatibility table lists minimal APIs as partially supported and MVC as not supported. I turned on PublishAot for UsOrdersApi to see what the analyzer says:

dotnet build --no-incremental -p:PublishAot=true
Program.cs(6,1): warning IL2026: Using member 'Microsoft.Extensions.DependencyInjection.MvcServiceCollectionExtensions.AddControllers(IServiceCollection)' which has 'RequiresUnreferencedCodeAttribute' can break functionality when trimming application code. MVC does not currently support trimming or native AOT. https://aka.ms/aspnet/trimming

The only warning landed on AddControllers. The minimal endpoints passed. For a real AOT app you’d also start from dotnet new webapiaot, use CreateSlimBuilder and register a JsonSerializerContext.

Organizing Minimal APIs at Scale

The fair complaint about minimal APIs is a 900-line Program.cs. That’s a habit, not a limit. My OrderEndpoints.cs already shows the pattern I use on bigger projects:

• One static class per resource with a Map*Endpoints extension method, so Program.cs stays at one line per feature.
• One MapGroup per resource for the prefix, tags, filters and RequireAuthorization().
• Named static handlers instead of long lambdas, so they’re testable and show up in stack traces.

You can see the same layout on a full EF Core app in my ASP.NET Core Web API CRUD tutorial. Controllers give you this folder structure by convention, which is why large teams that already know MVC often stay with them.

When to Use Controllers Instead of Minimal APIs

Here’s how I decide for a new endpoint today:

• New API on .NET 10, microservice or AOT target: minimal APIs.
• You need custom IModelBinder providers, IModelValidator, application parts or OData: controllers.
• Big existing MVC codebase with a team that knows it: keep controllers, and add new endpoints as minimal APIs if you like.
• Mixed needs: both in one app, exactly like this sample.

So the deciding differences are small: validation and OpenAPI now work in both, minimal APIs usually edge ahead on speed and win on testing and AOT, and controllers keep the MVC extensibility points. Check what changed in .NET 10 before you plan a migration.

A few more ASP.NET Core and C# guides from the site:

• All ASP.NET Core tutorials on AspDotnetHelp
• Interfaces in C# (IEndpointFilter is one)
• LINQ in C# for filtering results like the state query
• .NET Core interview questions and answers

Frequently Asked Questions

var tyler = FindCustomer("TX-1042");
Console.WriteLine(tyler!.Email!.ToUpper());

static Customer? FindCustomer(string id) =>
    id == "TX-1042" ? new Customer("Tyler Brooks", null) : null;

record Customer(string Name, string? Email);

Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Program.<Main>$(String[] args) in C:\DotNetDemo\NullableDemo\Crash.cs:line 2

Quick answer: keep <Nullable>enable</Nullable> on, mark values that can be missing as string?, and fix each warning with a null check, ??, a constructor or a required member.

Below is the playbook we follow on .NET 10, with real compiler output for each warning.

What You Need Before You Turn On Nullable Reference Types

• The .NET 10 SDK. Every demo is a single-file app (how dotnet run app.cs works), plus one small project.
• The sample: a US customer and order book (Tyler Brooks in Austin, Jenna Morales, ZIP codes, shipping addresses).
• One habit: nullable warnings print only when the compiler really runs. A cached dotnet run prints nothing, so I use dotnet run --no-cache File.cs or dotnet build --no-incremental.

Step 1: Enable Nullable in the .csproj (c# nullable enable)

New projects from the .NET 6 and later templates already have this line, and .NET 10 file-based apps turn it on by default. Older projects need it added to the PropertyGroup (not sure which SDK you’re on? check your .NET version first):

<Nullable>enable</Nullable>

The setting takes four values, and the same names work in a #nullable directive at the top of a file:

#nullable enable, #nullable disable and #nullable restore override the project value for the lines that follow; restore goes back to the .csproj setting.

Does string? Change Anything at Run Time?

No. A nullable reference type is a compile-time annotation only. string and string? are the same System.String, and nothing stops a null from getting in:

string name = "Jenna Morales";
string? nickname = null;

Console.WriteLine(name.GetType() == typeof(string));
Console.WriteLine(nickname is null);

string forced = null!;            // no warning, still null
Console.WriteLine(forced is null);

Output:

True
True
True

All three lines print True. That’s the key difference from nullable value types like int?, where int? really is a different type (Nullable<int>) with HasValue and Value.

Step 2: Read the Six Nullable Warnings You’ll See First

I packed five of the six warnings our team hits most into one file; CS8618 gets its own step. They only apply to reference types like string and classes, and each line is marked with the warning it causes:

string zip = LookupZip("Boise");            // CS8600
string? city = LookupZip("Boise");
Console.WriteLine(city.Length);             // CS8602
string? label = LookupZip("Boise");
PrintLabel(label);                          // CS8604
PrintLabel(null);                           // CS8625
Console.WriteLine(Shorten(zip));

static string? LookupZip(string city) => city == "Boise" ? "83702" : null;
static string Shorten(string? text) => text; // CS8603
static void PrintLabel(string text) => Console.WriteLine($"Label: {text}");

Output:

C:\DotNetDemo\NullableDemo\AllWarnings.cs(1,14): warning CS8600: Converting null literal or possible null value to non-nullable type.
C:\DotNetDemo\NullableDemo\AllWarnings.cs(3,19): warning CS8602: Dereference of a possibly null reference.
C:\DotNetDemo\NullableDemo\AllWarnings.cs(5,12): warning CS8604: Possible null reference argument for parameter 'text' in 'void PrintLabel(string text)'.
C:\DotNetDemo\NullableDemo\AllWarnings.cs(6,12): warning CS8625: Cannot convert null literal to non-nullable reference type.
C:\DotNetDemo\NullableDemo\AllWarnings.cs(10,40): warning CS8603: Possible null reference return.
5
Label: 83702
Label: 
83702

Every one is a warning, not an error, so the program still printed 5 and the labels. That’s why warnings pile up unless the team treats them as work.

Step 3: Fix CS8600, CS8602, CS8603, CS8604 and CS8625

Same ZIP lookup, now fixed. Reno isn’t in the lookup, so this run also proves the fallbacks work:

string zip = LookupZip("Reno") ?? "00000";        // CS8600: ??
string? city = LookupZip("Reno");
Console.WriteLine(city?.Length ?? 0);             // CS8602: ?.
string? label = LookupZip("Boise");
if (label is not null) PrintLabel(label);         // CS8604: null check
PrintLabel(zip);                                  // CS8625: pass a real value
Console.WriteLine($"[{Shorten(null)}]");          // CS8603: fallback

static string? LookupZip(string city) => city == "Boise" ? "83702" : null;
static string Shorten(string? text) => text ?? "";
static void PrintLabel(string text)
{
    ArgumentNullException.ThrowIfNull(text);      // guard public APIs
    Console.WriteLine($"Label: {text}");
}

Output:

0
Label: 83702
Label: 00000
[]

The build is clean. Reno’s city length falls back to 0, Boise prints its label, Reno’s ZIP becomes 00000, and Shorten(null) returns an empty string. The ways to check for null in C# cover is null versus == null in detail.

Our rule of thumb: use ?? when there’s a sensible default, ?. when skipping is fine, and a null check when the logic branches. For text that also can’t be blank, string.IsNullOrEmpty does both checks, and the compiler understands it.

Note: annotations don’t stop callers with nullable turned off from passing null. Public methods still need ArgumentNullException.ThrowIfNull.

Step 4: Fix CS8618 with a Constructor, required or a Default

CS8618 is the warning that floods a project on day one, mostly from model classes like this one:

var contact = new Contact();
Console.WriteLine(contact.Name is null);

class Contact
{
    public string Name { get; set; }
}

Output:

C:\DotNetDemo\NullableDemo\Cs8618.cs(6,19): warning CS8618: Non-nullable property 'Name' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the property as nullable.
True

The warning even suggests the fixes, and the second line proves the point: Name really is null. There are four honest fixes, and I put all four in one file:

var tyler = new Customer("Tyler Brooks", "tyler@example.com");
var jenna = new Contact { Name = "Jenna Morales" };

Console.WriteLine($"{tyler.Name} <{tyler.Email}>");
Console.WriteLine($"{jenna.Name}, {jenna.Phone ?? "no phone"}");
Console.WriteLine($"Notes: '{jenna.Notes}'");

class Customer(string name, string email)   // 1
{
    public string Name { get; } = name;
    public string Email { get; } = email;
}

class Contact
{
    public required string Name { get; init; }  // 2
    public string? Phone { get; init; }         // 3
    public string Notes { get; set; } = "";     // 4
}

Output:

Tyler Brooks <tyler@example.com>
Jenna Morales, no phone
Notes: ''

In order: 1 is a constructor for values known at creation, 2 is required (C# 11+) for object-initializer models, 3 is string? for values that can really be missing, and 4 is a default like "", only when empty means something.

required moves the check to the caller. Forget the property and you get a compile error instead of a null:

var contact = new Contact();
Console.WriteLine(contact.Name);

class Contact
{
    public required string Name { get; init; }
}

Build output:

C:\DotNetDemo\NullableDemo\RequiredMissing.cs(1,19): error CS9035: Required member 'Contact.Name' must be set in the object initializer or attribute constructor.

The build failed. Fix the build errors and run again.

That’s CS9035, and it’s exactly what we want: the missing name is caught at build time, not in production.

Step 5: Use the Null-Forgiving Operator (!) Only as a Last Resort

The ! in the opening example tells the compiler “trust me”. It changes nothing at run time, which is why Tyler’s missing email still threw NullReferenceException.

We allow ! in two places only: tests that pass null! on purpose, and members a framework fills in, like an EF Core DbSet<T> declared = null! (our Web API CRUD with EF Core build skips even that with => Set<Product>()).

Everywhere else, a pull request with ! needs a comment saying why.

Step 6: Teach the Compiler with [NotNullWhen], [MaybeNull] and [MemberNotNull]

The compiler doesn’t look inside your methods, so a helper that checks for null still leaves callers with warnings. The attributes in System.Diagnostics.CodeAnalysis describe the contract instead:

using System.Diagnostics.CodeAnalysis;

var book = new CustomerBook();
if (book.TryGetEmail("Tyler Brooks", out string? email))
    Console.WriteLine(email.ToUpperInvariant());     // no CS8602
Console.WriteLine(book.Region.Length);
string[] states = ["Texas", "Ohio"];
Console.WriteLine(FirstMatch(states, s => s.StartsWith('V')) is null);

[return: MaybeNull]
static T FirstMatch<T>(IEnumerable<T> items, Func<T, bool> match)
{
    foreach (T item in items) if (match(item)) return item;
    return default;
}

class CustomerBook
{
    private readonly Dictionary<string, string> emails = new() { ["Tyler Brooks"] = "tyler.brooks@example.com" };
    public string Region { get; private set; }
    public CustomerBook() => Load();

    [MemberNotNull(nameof(Region))]
    private void Load() => Region = "Pacific Northwest";

    public bool TryGetEmail(string name, [NotNullWhen(true)] out string? email) =>
        emails.TryGetValue(name, out email);
}

Output:

TYLER.BROOKS@EXAMPLE.COM
17
True

No warnings. [NotNullWhen(true)] says email isn’t null when TryGetEmail returns true, [MemberNotNull] says Load() sets Region, so there’s no CS8618, and [return: MaybeNull] lets the generic method return default.

The output is the uppercase email, 17 (the length of Pacific Northwest), and True because no state starts with V. The pattern matching guide shows how is { } and is not null narrow null the same way.

Step 7: Turn Nullable Warnings into Build Errors

Warnings that never fail a build get ignored. Once a project is clean, we lock it with WarningsAsErrors. Here’s the file from a plain console project in VS Code:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WarningsAsErrors>nullable</WarningsAsErrors>
  </PropertyGroup>

</Project>

And a Program.cs with two classic bugs, a missing Customer initializer and an unchecked ShipTo:

var order = new Order { Id = 1042, Customer = "Tyler Brooks" };
Console.WriteLine(order.ShipTo.City);

class Order
{
    public int Id { get; init; }
    public string Customer { get; init; }
    public Address? ShipTo { get; init; }
}

record Address(string City, string State);

dotnet build output:

  Determining projects to restore...
  Restored C:\DotNetDemo\NullableDemo\Orders\Orders.csproj (in 73 ms).
C:\DotNetDemo\NullableDemo\Orders\Program.cs(7,19): error CS8618: Non-nullable property 'Customer' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the property as nullable. [C:\DotNetDemo\NullableDemo\Orders\Orders.csproj]
C:\DotNetDemo\NullableDemo\Orders\Program.cs(2,19): error CS8602: Dereference of a possibly null reference. [C:\DotNetDemo\NullableDemo\Orders\Orders.csproj]
Build FAILED.
C:\DotNetDemo\NullableDemo\Orders\Program.cs(7,19): error CS8618: Non-nullable property 'Customer' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the property as nullable. [C:\DotNetDemo\NullableDemo\Orders\Orders.csproj]
C:\DotNetDemo\NullableDemo\Orders\Program.cs(2,19): error CS8602: Dereference of a possibly null reference. [C:\DotNetDemo\NullableDemo\Orders\Orders.csproj]
    0 Warning(s)
    2 Error(s)
Time Elapsed 00:00:01.18

The string nullable covers every nullability warning, so new ones fail CI without a list of numbers. <TreatWarningsAsErrors>true</TreatWarningsAsErrors> fails on every warning, nullable or not; we turn that on only in clean, mature projects.

How Do You Migrate an Existing Project Gradually?

Don’t flip a 300-file project to enable in one pull request. Set the project to enable, add #nullable disable to the files you haven’t migrated, and remove one directive per file as you fix it:

Console.WriteLine(LegacyFormat(null, null));
Console.WriteLine(ModernFormat(null));

#nullable disable
static string LegacyFormat(string name, string? suffix) =>
    name == null ? "(no name)" : name.ToUpper() + suffix;
#nullable restore

static string ModernFormat(string? name) =>
    name is null ? "(no name)" : name.ToUpper();

Output:

C:\DotNetDemo\NullableDemo\LegacyHelper.cs(5,47): warning CS8632: The annotation for nullable reference types should only be used in code within a '#nullable' annotations context.
(no name)
(no name)

Both calls print (no name) and LegacyFormat(null, null) raises no warning, because its parameters are oblivious. The string? inside the disabled region causes CS8632, a sign that file is half-migrated.

Start with the leaf classes (models, helpers) and work outward, since annotating a type creates warnings in its callers. Moving to .NET 10 at the same time? Do the .NET 8 to .NET 10 upgrade first, then the nullable pass.

Our Team Rules for Nullable Reference Types

1. <Nullable>enable</Nullable> in every project; no new #nullable disable.
2. ? means “can really be missing”. If it can’t, fix the initialization instead.
3. ! and = null! need a code comment, and only for tests or framework-filled members.
4. Models use constructors or required; no empty-string defaults just to quiet CS8618.
5. Clean projects set <WarningsAsErrors>nullable</WarningsAsErrors>.

Common Mistakes to Avoid

Next Steps

Once warnings are under control, try the newer null-friendly syntax, such as null-conditional assignment (customer?.Email = ...) in what is new in C# 14. Records also pair well with non-nullable properties; see record vs class vs struct.

Good follow-ups from our team’s reading list:

• Try-catch in C#, for the NullReferenceException you still need to handle
• Interfaces in C#, where nullability must match the implementation
• What’s new in .NET 10
• All C# tutorials on AspDotnetHelp

Frequently Asked Questions

Blazor components fix that: you write the card once as a .razor file, pass each product in with [Parameter] properties, and send clicks back to the page with EventCallback. We’ll build that store on .NET 10, one component at a time.

Here’s what we’re building:

• ProductCard: one card per product, with a quantity stepper and an Add to cart button
• Panel: a titled box that wraps whatever markup you put inside it
• OrderList: the cart lines and subtotal, with its C# in a code-behind file

Before You Start Building Blazor Components

You need the .NET 10 SDK (I used 10.0.402) and an editor; I use VS Code. If dotnet --version doesn’t print 10.x, check which .NET versions you have first.

If you’ve never run a Blazor app, my Blazor tutorial for beginners covers pages and routing. This post stays on components. The sample data is six products, all priced in USD:

What Is a Blazor Component?

A Blazor component is a .razor file that mixes HTML markup with a C# @code block. The compiler turns each file into a C# partial class that inherits ComponentBase, named after the file. That’s plain C# inheritance at work.

A page is just a component with @page. Everything below works the same in both.

Step 1: Create a Blazor Web App in .NET 10

Create the app from the Blazor Web App template. Its default interactivity is Server, applied per page:

dotnet new blazor -o BlazorComponents
cd BlazorComponents

I deleted the two appsettings files (this demo doesn’t use them) and trimmed Properties/launchSettings.json to one http profile on port 5791:

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5791",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

The project file and Program.cs are what the template wrote for .NET 10. Program.cs already registers the Interactive Server services we’ll need in Step 4:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>
  </PropertyGroup>

</Project>

using BlazorComponents.Components;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.UseAntiforgery();

app.MapStaticAssets();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

New components go in the Components folder. The template’s _Imports.razor already has @using BlazorComponents.Components, so pages can use them without extra lines.

Checkpoint: dotnet run prints Now listening on: http://localhost:5791, and the browser shows “Hello, world!”.

Step 2: Build Your First Blazor Component with [Parameter]

First, the data types in Models/ShopModels.cs. They’re C# records, so each one is a single line plus the cart total:

namespace BlazorComponents.Models;

public record Product(int Id, string Name, string Category, decimal Price);

public record CartLine(Product Product, int Quantity)
{
    public decimal Total => Product.Price * Quantity;
}

public record StoreInfo(string Name, string City, decimal FreeShippingOver);

Now the component, Components/ProductCard.razor. The Product property is the [Parameter] the parent fills in:

@using System.Globalization
@using BlazorComponents.Models

<div class="card mb-2">
    <div class="card-body py-2">
        <h5 class="card-title mb-1">@Product.Name</h5>
        <p class="mb-0">@Product.Category · @Product.Price.ToString("C", Us)</p>
    </div>
</div>

@code {
    private static readonly CultureInfo Us = new("en-US");

    [Parameter, EditorRequired]
    public Product Product { get; set; } = default!;
}

The "C" format with an en-US culture always prints dollars, even on a PC set to another region (more in formatting numbers in C#).

Then the page, Components/Pages/Shop.razor. It loops over the products and passes each one as an attribute:

@page "/shop"
@using BlazorComponents.Models

<PageTitle>Shop</PageTitle>

<h1>Cascade Trail Outfitters</h1>

<div class="row">
    <div class="col-md-7">
        @foreach (var product in products)
        {
            <ProductCard Product="product" />
        }
    </div>
</div>

@code {
    private List<Product> products =
    [
        new(1, "Trail Daypack 24L", "Packs", 64.99m),
        new(2, "Insulated Water Bottle", "Hydration", 24.50m),
        new(3, "Two-Person Tent", "Camping", 189.00m),
        new(4, "Headlamp 400", "Lighting", 34.95m),
        new(5, "Rain Shell Jacket", "Apparel", 119.00m),
        new(6, "Camp Stove", "Cooking", 79.99m),
    ];
}

Keep parameters as plain auto-properties. Microsoft Learn warns that logic in a parameter’s set can cause an infinite render loop.

Checkpoint: curl of /shop returned 200 with six cards, starting with “Packs · $64.99”.

Step 3: Make a Blazor Component Parameter Required with [EditorRequired]

[EditorRequired] tells the editor and the build that a parent must set the parameter. To see it, I added a card with no product under the loop:

<ProductCard />

dotnet build --no-incremental printed this warning:

Components\Pages\Shop.razor(14,9): warning RZ2012: Component 'ProductCard' expects a value for the parameter 'Product', but a value may not have been provided.

It’s only a warning, so the build still succeeds. At runtime, curl of /shop returned 500:

NullReferenceException: Object reference not set to an instance of an object.
at BlazorComponents.Components.ProductCard.BuildRenderTree(RenderTreeBuilder __builder) in C:\DotNetDemo\BlazorComponents\Components\ProductCard.razor:line 6

The attribute isn’t checked at runtime and doesn’t promise a non-null value, so null checks still matter for optional parameters. I removed the broken tag before moving on.

Checkpoint: one RZ2012 warning in the build output, and none once the tag is gone.

Step 4: Send Clicks from Child to Parent with EventCallback

The card has the Add button, but the cart lives in the page. A child can’t reach into its parent, so it exposes an EventCallback<CartLine> parameter and invokes it:

@using System.Globalization
@using BlazorComponents.Models

<div class="card mb-2">
    <div class="card-body py-2">
        <h5 class="card-title mb-1">@Product.Name</h5>
        <p class="mb-2">@Product.Category · @Product.Price.ToString("C", Us)</p>
        <button class="btn btn-outline-secondary btn-sm minus" @onclick="() => quantity = Math.Max(1, quantity - 1)">-</button>
        <span class="qty mx-2">@quantity</span>
        <button class="btn btn-outline-secondary btn-sm plus" @onclick="() => quantity++">+</button>
        <button class="btn btn-primary btn-sm ms-2 add" @onclick="Add">Add to cart</button>
    </div>
</div>

@code {
    private static readonly CultureInfo Us = new("en-US");
    private int quantity = 1;

    [Parameter, EditorRequired]
    public Product Product { get; set; } = default!;

    [Parameter]
    public EventCallback<CartLine> OnAdd { get; set; }

    private async Task Add() => await OnAdd.InvokeAsync(new CartLine(Product, quantity));
}

The quantity field is the card’s own private state. Learn recommends the typed EventCallback<TValue> over plain EventCallback, because a wrong argument type then fails at compile time.

In the page, hand the callback a method and give the page a render mode. Here’s the updated Shop.razor:

@page "/shop"
@rendermode InteractiveServer
@using BlazorComponents.Models

<PageTitle>Shop</PageTitle>

<h1>Cascade Trail Outfitters</h1>

<div class="row">
    <div class="col-md-7">
        @foreach (var product in products)
        {
            <ProductCard Product="product" OnAdd="AddToCart" />
        }
    </div>
    <div class="col-md-5">
        <p class="cart">Cart: @cart.Count line(s), @cart.Sum(l => l.Quantity) item(s)</p>
    </div>
</div>

@code {
    private List<Product> products =
    [
        new(1, "Trail Daypack 24L", "Packs", 64.99m),
        new(2, "Insulated Water Bottle", "Hydration", 24.50m),
        new(3, "Two-Person Tent", "Camping", 189.00m),
        new(4, "Headlamp 400", "Lighting", 34.95m),
        new(5, "Rain Shell Jacket", "Apparel", 119.00m),
        new(6, "Camp Stove", "Cooking", 79.99m),
    ];
    private readonly List<CartLine> cart = [];

    private void AddToCart(CartLine line) => cart.Add(line);
}

You don’t call StateHasChanged in AddToCart. Blazor rerenders the parent after an EventCallback runs, which is how it differs from a raw C# delegate like Action<T>.

I tried it first without the @rendermode InteractiveServer line. After three clicks, the page still said “Cart: 0 line(s), 0 item(s)”, because a page without a render mode is static HTML.

With the line back, the same clicks gave “Cart: 2 line(s), 3 item(s)”. My Blazor render modes guide explains what each mode does.

Checkpoint: Add on the Daypack, then + and Add on the Tent: “Cart: 2 line(s), 3 item(s)”.

Step 5: Pass Markup to a Blazor Component with ChildContent

A parameter can also carry markup. Name a RenderFragment parameter ChildContent, and whatever sits between the component’s tags lands there. Here’s Components/Panel.razor:

<div class="card">
    <div class="card-header fw-bold">@Title</div>
    <div class="card-body">
        @ChildContent
    </div>
</div>

@code {
    [Parameter]
    public string Title { get; set; } = "";

    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

The name matters: Blazor only maps the content between the tags to a property called ChildContent. In the page, the cart text moves inside the panel:

        <Panel Title="Your order">
            <p class="cart">Cart: @cart.Count line(s), @cart.Sum(l => l.Quantity) item(s)</p>
            <p class="text-muted mb-0">Free shipping on orders over $75.</p>
        </Panel>

Checkpoint: the right column shows “Your order” with “Cart: 2 line(s), 3 item(s)” inside it.

Step 6: Move Component Logic to a Code-Behind Partial Class

For the cart list, I split markup and C# into two files. Components/OrderList.razor holds only markup:

@if (Lines.Count == 0)
{
    <p class="text-muted mb-0">Your cart is empty.</p>
}
else
{
    <ul class="list-group mb-2">
        @foreach (var line in Lines)
        {
            <li class="list-group-item d-flex justify-content-between align-items-center">
                <span>@line.Quantity x @line.Product.Name</span>
                <span>
                    @Money(line.Total)
                    <button class="btn btn-link btn-sm remove" @onclick="() => OnRemove.InvokeAsync(line)">Remove</button>
                </span>
            </li>
        }
    </ul>
    <p class="fw-bold mb-0 subtotal">Subtotal: @Money(Subtotal) (@ItemCount items)</p>
}

And Components/OrderList.razor.cs holds the class. It’s a partial class with the same name and namespace as the .razor file:

using System.Globalization;
using BlazorComponents.Models;
using Microsoft.AspNetCore.Components;

namespace BlazorComponents.Components;

public partial class OrderList : ComponentBase
{
    private static readonly CultureInfo Us = new("en-US");

    [Parameter, EditorRequired]
    public IReadOnlyList<CartLine> Lines { get; set; } = [];

    [Parameter]
    public EventCallback<CartLine> OnRemove { get; set; }

    private decimal Subtotal => Lines.Sum(l => l.Total);
    private int ItemCount => Lines.Sum(l => l.Quantity);

    private static string Money(decimal value) => value.ToString("C", Us);
}

Two details trip people up. _Imports.razor doesn’t apply to .cs files, so the using lines are needed, and : ComponentBase is optional because the .razor half already sets it.

The subtotal is a LINQ Sum over the lines. In the page, the panel now wraps the new component, and RemoveLine handles its callback:

        <Panel Title="Your order">
            <OrderList Lines="cart" OnRemove="RemoveLine" />
        </Panel>

@code {
    ...
    private void RemoveLine(CartLine line) => cart.Remove(line);
}

Checkpoint: after adding the Headlamp too: “Subtotal: $477.94 (4 items)”. Remove on the Tent line left “Subtotal: $99.94 (2 items)”.

Step 7: Share Values with a Blazor Cascading Parameter

Every card needs the store’s free shipping threshold, and passing it to each card by hand gets old. A CascadingValue hands a value to every component below it. The loop in Shop.razor becomes:

        <CascadingValue Value="store" IsFixed="true">
            @foreach (var product in products)
            {
                <ProductCard Product="product" OnAdd="AddToCart" />
            }
        </CascadingValue>

The page also gets a store field: new("Cascade Trail Outfitters", "Portland, OR", 75m). IsFixed="true" says it won’t change, so Blazor skips change tracking.

The card picks it up with [CascadingParameter], matched by type. Here’s the finished ProductCard.razor:

@using System.Globalization
@using BlazorComponents.Models

<div class="card mb-2">
    <div class="card-body py-2">
        <h5 class="card-title mb-1">@Product.Name</h5>
        <p class="mb-2">@Product.Category · @Product.Price.ToString("C", Us)</p>
        @if (Store is not null && Product.Price >= Store.FreeShippingOver)
        {
            <p class="mb-2"><span class="badge text-bg-success">Free shipping from @Store.City</span></p>
        }
        <button class="btn btn-outline-secondary btn-sm minus" @onclick="() => quantity = Math.Max(1, quantity - 1)">-</button>
        <span class="qty mx-2">@quantity</span>
        <button class="btn btn-outline-secondary btn-sm plus" @onclick="() => quantity++">+</button>
        <button class="btn btn-primary btn-sm ms-2 add" @onclick="Add">Add to cart</button>
    </div>
</div>

@code {
    private static readonly CultureInfo Us = new("en-US");
    private int quantity = 1;

    [Parameter, EditorRequired]
    public Product Product { get; set; } = default!;

    [Parameter]
    public EventCallback<CartLine> OnAdd { get; set; }

    [CascadingParameter]
    private StoreInfo? Store { get; set; }

    private async Task Add() => await OnAdd.InvokeAsync(new CartLine(Product, quantity));
}

For an app-wide value, register it as a service with builder.Services.AddCascadingValue(...), the same container as in DI lifetimes in ASP.NET Core.

Important: cascading values don’t cross render mode boundaries. A CascadingValue in a static layout won’t reach an interactive page, while a root-level AddCascadingValue will.

Checkpoint: badges on 3 cards, the ones at $75 or more: Two-Person Tent, Rain Shell Jacket, Camp Stove.

Step 8: Keep Component State in Lists with @key

Last, a Sort by price button. Here’s the final Shop.razor; note @key="product.Id" on the card:

@page "/shop"
@rendermode InteractiveServer
@using BlazorComponents.Models

<PageTitle>Shop</PageTitle>

<h1>Cascade Trail Outfitters</h1>

<button class="btn btn-secondary btn-sm mb-3 sort" @onclick="SortByPrice">Sort by price</button>

<div class="row">
    <div class="col-md-7">
        <CascadingValue Value="store" IsFixed="true">
            @foreach (var product in products)
            {
                <ProductCard @key="product.Id" Product="product" OnAdd="AddToCart" />
            }
        </CascadingValue>
    </div>
    <div class="col-md-5">
        <Panel Title="Your order">
            <OrderList Lines="cart" OnRemove="RemoveLine" />
        </Panel>
    </div>
</div>

@code {
    private readonly StoreInfo store = new("Cascade Trail Outfitters", "Portland, OR", 75m);
    private List<Product> products =
    [
        new(1, "Trail Daypack 24L", "Packs", 64.99m),
        new(2, "Insulated Water Bottle", "Hydration", 24.50m),
        new(3, "Two-Person Tent", "Camping", 189.00m),
        new(4, "Headlamp 400", "Lighting", 34.95m),
        new(5, "Rain Shell Jacket", "Apparel", 119.00m),
        new(6, "Camp Stove", "Cooking", 79.99m),
    ];
    private readonly List<CartLine> cart = [];

    private void AddToCart(CartLine line) => cart.Add(line);
    private void RemoveLine(CartLine line) => cart.Remove(line);
    private void SortByPrice() => products = [.. products.OrderBy(p => p.Price)];
}

I ran the test without @key first: + twice on the Daypack, so it showed 3, then Sort. Row 1 became “Insulated Water Bottle qty 3”, and the Daypack in row 3 dropped back to 1.

Without a key, Blazor reuses the card in row 1 and only swaps its Product parameter, so the private quantity stays behind. With @key, the same clicks left “Trail Daypack 24L qty 3” in row 3.

SortByPrice builds a new List rather than sorting in place, which is fine. Use a unique, stable key such as a database id or the object itself.

Duplicate keys under one parent throw an exception, and keys only compare among siblings.

Checkpoint: after sorting with @key, the Daypack sits third and still shows 3.

Test the Blazor Components

Here’s every check I ran on the finished app, with the real results:

The page is still prerendered: curl got full HTML plus a <!--Blazor: marker. That’s why my headless runs wait 3.5 seconds before clicking, so the circuit is connected.

Troubleshooting Common Blazor Component Parameter Mistakes

Writing to a parameter inside the child. This QtyBadge.razor increments its own Quantity parameter:

@using BlazorComponents.Models

<p class="mb-2">
    @Product.Name: <span class="qty">@Quantity</span>
    <button class="btn btn-outline-secondary btn-sm plus" @onclick="() => Quantity++">+</button>
</p>

@code {
    [Parameter, EditorRequired]
    public Product Product { get; set; } = default!;

    [Parameter]
    public int Quantity { get; set; }   // the child writes to its own parameter: don't
}

I used it on a test page, Components/Pages/Mistake.razor, with a button that only rerenders the parent:

@page "/mistake"
@rendermode InteractiveServer
@using BlazorComponents.Models

<PageTitle>Mistake</PageTitle>

<h1>Writing to a parameter</h1>

<QtyBadge Product="headlamp" Quantity="1" />

<p>Parent renders: <span class="renders">@renders</span></p>
<button class="btn btn-secondary btn-sm refresh" @onclick="() => renders++">Re-render parent</button>

@code {
    private readonly Product headlamp = new(4, "Headlamp 400", "Lighting", 34.95m);
    private int renders = 1;
}

Two clicks on + showed 3. One click on Re-render parent reset it to 1, because the parent sent Quantity="1" again. Keep the value in a private field, as ProductCard does, and report changes with an EventCallback, Blazor’s take on C# events.

Buttons that do nothing. The page has no @rendermode, so it’s static SSR. Add @rendermode InteractiveServer to the page, as in Step 4.

A component tag that renders as plain HTML. The file name starts with a lowercase letter, or its namespace isn’t imported. Rename it to ProductCard.razor and check _Imports.razor.

required or init on a parameter. Learn says not to use either. Blazor sets parameters by reflection, which bypasses both, so use [EditorRequired] instead.

Where to Take It Next with Blazor Components

Swap the hard-coded list for real data and a grid. My Blazor QuickGrid tutorial sorts and pages 200 orders with the same kind of component parameters.

You can also make ProductCard generic with @typeparam, or add two-way binding with a Value parameter plus a ValueChanged callback. New posts land in the Blazor tutorials.

A few more reads for the C# behind these components:

• More ASP.NET Core tutorials for the server side
• Interfaces in C# for swappable services
• New C# 14 features you can use in @code blocks
• Upgrade a .NET 8 Blazor app to .NET 10

Frequently Asked Questions

The order you register them in Program.cs is the order they run, and the response travels back in reverse. I built a .NET 10 orders API with a request timer, a correlation ID and an API-key check, then broke its order on purpose.

What Is the ASP.NET Core Middleware Pipeline?

The pipeline is a list of request delegates called one after another. A RequestDelegate is just a delegate in C# that takes an HttpContext and returns a Task.

Code before await next(context) works on the request on its way in. Code after it runs on the way out, once everything later in the pipeline has finished. That’s why exception handlers go first: they wrap everything below them.

The Sample Orders API We’ll Use for Middleware

Everything runs on the .NET 10 SDK (10.0.402); check your .NET version if you’re not sure what you have. The main project is an empty web template called OrdersApi:

dotnet new web -n OrdersApi -o OrdersApi

It serves three orders from Austin, Columbus and Seattle. Four endpoints exercise the pipeline in different ways:

I deleted appsettings.Development.json and the Properties folder, and I start it with dotnet run -- --urls http://localhost:5790 --environment Development. Here are the project file and appsettings.json, both straight from the template:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

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

Method 1: Inline Middleware with app.Use and app.Run (Recommended to Start)

Inline middleware is the fastest way to see how the pipeline behaves, and it’s fine in real apps for one-off jobs like the bot blocker you’ll see later.

This demo, like the next two, is one of the file-based apps that .NET 10 added. The #:sdk Microsoft.NET.Sdk.Web line makes it a web app that starts, calls itself and stops.

Same order #1042 from the sample data. Here’s the code, with two Use calls and one Run:

#:sdk Microsoft.NET.Sdk.Web
var builder = WebApplication.CreateBuilder();
builder.Logging.ClearProviders();
var app = builder.Build();

app.Use(async (context, next) =>
{
    Console.WriteLine("1. Logger: request in");
    await next(context);
    Console.WriteLine("1. Logger: response out");
});
app.Use(async (context, next) =>
{
    Console.WriteLine("2. Timer: request in");
    await next(context);
    Console.WriteLine("2. Timer: response out");
});
app.Run(async context =>
{
    Console.WriteLine("3. Run: writes the response");
    await context.Response.WriteAsync("Order #1042 shipped to Austin, TX");
});

app.Urls.Add("http://localhost:5790");
await app.StartAsync();
Console.WriteLine(await new HttpClient().GetStringAsync("http://localhost:5790/"));
await app.StopAsync();

Output:

1. Logger: request in
2. Timer: request in
3. Run: writes the response
2. Timer: response out
1. Logger: response out
Order #1042 shipped to Austin, TX

The client got Order #1042 shipped to Austin, TX, and the console shows the request going in and coming back out in reverse.

How does this work?

The first app.Use prints its line, then await next(context) hands the request to the second one. That one prints and calls next too, which reaches app.Run.

app.Run has no next parameter, so it’s terminal. It writes the response, and control unwinds back through the second and then the first middleware, which is why the out lines come in reverse order.

Note: Use has two overloads. Prefer the one where next is a RequestDelegate and you call next(context); Microsoft says it saves two internal allocations per request over the Func<Task> one.

Method 2: Branch the Middleware Pipeline with Map, MapWhen and UseWhen

Branch when only some requests need different middleware: a health check, an old API version or an admin area.

Here’s the code, with paths borrowed from the same orders API:

#:sdk Microsoft.NET.Sdk.Web
var builder = WebApplication.CreateBuilder();
builder.Logging.ClearProviders();
var app = builder.Build();

app.Map("/health", health => health.Run(c => c.Response.WriteAsync("Healthy")));
app.MapWhen(c => c.Request.Query.ContainsKey("legacy"),
    v1 => v1.Run(c => c.Response.WriteAsync("Legacy v1 orders")));
app.UseWhen(c => c.Request.Path.StartsWithSegments("/admin"),
    admin => admin.Use(async (c, next) =>
    {
        c.Response.Headers["X-Admin-Area"] = "true";
        await next(c);
    }));
app.Run(c => c.Response.WriteAsync($"Main pipeline: {c.Request.Path}"));

app.Urls.Add("http://localhost:5790");
await app.StartAsync();
var http = new HttpClient { BaseAddress = new Uri("http://localhost:5790") };
foreach (var path in new[] { "/health", "/orders?legacy=1", "/admin/report", "/orders" })
{
    var res = await http.GetAsync(path);
    var tag = res.Headers.Contains("X-Admin-Area") ? "  [X-Admin-Area: true]" : "";
    Console.WriteLine($"{path,-17} -> {await res.Content.ReadAsStringAsync()}{tag}");
}
await app.StopAsync();

Output:

/health           -> Healthy
/orders?legacy=1  -> Legacy v1 orders
/admin/report     -> Main pipeline: /admin/report  [X-Admin-Area: true]
/orders           -> Main pipeline: /orders

How does this work?

app.Map("/health", ...) matched the path prefix and ran its own Run, so the answer was Healthy. Map also moves the matched segment from Request.Path to Request.PathBase inside the branch.

app.MapWhen takes any Func<HttpContext, bool>; Query.ContainsKey works like it does on a Dictionary in C#. The ?legacy=1 request went into its branch and never came back to the main pipeline.

app.UseWhen is different. It added the X-Admin-Area header to /admin/report, then rejoined the main pipeline, so the main Run still wrote the body.

Important: app.Map branches the middleware pipeline. It isn’t app.MapGet, which maps an endpoint for routing.

Method 3: Write a Custom Middleware Class (Convention-Based)

Once middleware has more than a few lines, move it into a class. Microsoft’s rules for a convention-based class are short:

• a public constructor with a RequestDelegate parameter;
• a public method named Invoke or InvokeAsync that returns a Task and takes an HttpContext first;
• any other constructor or InvokeAsync parameters come from dependency injection.

Here’s the request timing middleware for the same orders API, with its UseRequestTiming extension method in the same file (Middleware/RequestTimingMiddleware.cs):

using System.Diagnostics;

namespace OrdersApi.Middleware;

// Convention-based middleware: created once at startup, InvokeAsync runs for every request.
public class RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
{
    public const string Header = "X-Response-Time-ms";

    public async Task InvokeAsync(HttpContext context)
    {
        var timer = Stopwatch.StartNew();
        context.Response.OnStarting(() =>
        {
            // runs just before the headers go out, so it's still safe to add one
            context.Response.Headers[Header] = timer.ElapsedMilliseconds.ToString();
            return Task.CompletedTask;
        });
        try
        {
            await next(context);
        }
        finally
        {
            logger.LogInformation("{Method} {Path} -> {Status} in {Elapsed} ms",
                context.Request.Method, context.Request.Path, context.Response.StatusCode, timer.ElapsedMilliseconds);
        }
    }
}

public static class RequestTimingExtensions
{
    public static IApplicationBuilder UseRequestTiming(this IApplicationBuilder app) =>
        app.UseMiddleware<RequestTimingMiddleware>();
}

Program.cs adds it with app.UseRequestTiming(); right after the exception handler, so you’ll see an X-Response-Time-ms header on every response.

How does this work?

The Stopwatch starts as the request arrives. Response.OnStarting runs its callback just before the headers go out, so the header lands even though an endpoint writes the body later.

The log line sits in a finally block, the same idea as a try-catch-finally in C#: it still runs when something deeper throws. The await keeps it all non-blocking, as in async/await in C#.

The extension method just wraps UseMiddleware<RequestTimingMiddleware>(), the same UseXxx pattern the built-in middleware uses.

Important: this class is built once, when the app starts, so never put a scoped service in its constructor. I added CorrelationContext there as a test, and the API wouldn’t even start in Development:

System.InvalidOperationException: Cannot resolve scoped service 'OrdersApi.Middleware.CorrelationContext' from root provider.

Ask for scoped services as extra InvokeAsync parameters instead. My DI lifetimes guide for ASP.NET Core explains why a singleton can’t hold a scoped service.

Method 4: Factory-Based Middleware with IMiddleware and Scoped Services

If your middleware needs scoped services in its constructor, implement IMiddleware. ASP.NET Core resolves it from DI for every request, and you get strong typing from the interface.

Same orders API, now with a correlation ID that ties a request to its log lines (Middleware/CorrelationIdMiddleware.cs):

namespace OrdersApi.Middleware;

// Scoped: one instance per request, shared by the middleware and the endpoint.
public class CorrelationContext
{
    public string CorrelationId { get; set; } = "";
}

// Factory-based middleware: resolved from DI for every request, so scoped services can go in the constructor.
public class CorrelationIdMiddleware(CorrelationContext correlation, ILogger<CorrelationIdMiddleware> logger) : IMiddleware
{
    public const string Header = "X-Correlation-ID";

    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        string? incoming = context.Request.Headers[Header];
        correlation.CorrelationId = string.IsNullOrWhiteSpace(incoming)
            ? Guid.NewGuid().ToString("N")[..12]
            : incoming;
        context.Response.Headers[Header] = correlation.CorrelationId;   // nothing is written yet

        logger.LogInformation("{Id} {Path} user={User}", correlation.CorrelationId,
            context.Request.Path, context.User.Identity?.Name ?? "anonymous");
        await next(context);
    }
}

public static class CorrelationIdExtensions
{
    public static IApplicationBuilder UseCorrelationId(this IApplicationBuilder app) =>
        app.UseMiddleware<CorrelationIdMiddleware>();
}

Program.cs registers both classes with AddScoped<CorrelationContext>() and AddTransient<CorrelationIdMiddleware>(), then calls app.UseCorrelationId() after authorization.

How does this work?

UseMiddleware sees that the class implements IMiddleware and asks the IMiddlewareFactory for an instance. That’s why the class has to be registered, as scoped or transient.

It reuses the caller’s X-Correlation-ID or makes a short GUID in C#. The header is set before next, while nothing is written yet.

The /orders endpoint asks for CorrelationContext too, and because it’s scoped, it’s the same object, so the JSON echoes the ID back.

Important: I deleted the AddTransient line to see what breaks. The app started, but every request returned 500 with this logged:

System.InvalidOperationException: No service for type 'OrdersApi.Middleware.CorrelationIdMiddleware' has been registered.

Also, you can’t pass extra arguments to an IMiddleware class through UseMiddleware<T>(args); Microsoft documents that as a NotSupportedException. The interface in C# contract is the only signature it gets.

The Recommended ASP.NET Core Middleware Order

Microsoft’s rule: the order in the Program file is the order middleware runs on a request, and the reverse on the response. Here’s the order the docs recommend for common apps, with my one-line reason for each:

Here’s the full Program.cs of the sample orders API in that order. The timing middleware and the bot blocker go up front on purpose, because they should see every request:

using System.Globalization;
using Microsoft.AspNetCore.Authentication;
using OrdersApi;
using OrdersApi.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails();
builder.Services.AddCors(o => o.AddDefaultPolicy(p => p.WithOrigins("https://shop.example.com")));
builder.Services.AddAuthentication(ApiKeyHandler.SchemeName)
    .AddScheme<AuthenticationSchemeOptions, ApiKeyHandler>(ApiKeyHandler.SchemeName, null);
builder.Services.AddAuthorization();
builder.Services.AddScoped<CorrelationContext>();
builder.Services.AddTransient<CorrelationIdMiddleware>();   // IMiddleware classes must be registered

var app = builder.Build();

// 1. Exception handler first, so it catches errors thrown anywhere below it
app.UseExceptionHandler();
if (!app.Environment.IsDevelopment())
{
    app.UseHsts();
}
// app.UseHttpsRedirection();   // on in production; this demo listens on http only
// app.UseStaticFiles();        // or app.MapStaticAssets() when the app serves files

// 2. Custom middleware that must see every request
app.UseRequestTiming();
app.Use(async (context, next) =>
{
    var path = context.Request.Path;
    if (path.StartsWithSegments("/wp-admin") || path.Value!.EndsWith(".php"))
    {
        context.Response.StatusCode = StatusCodes.Status404NotFound;
        return;                                  // short-circuit: next is never called
    }
    await next(context);
});

// 3. Routing, CORS, authentication, authorization - in this order
app.UseRouting();
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

// 4. Custom middleware that needs the matched endpoint and the signed-in user
app.UseCorrelationId();

// 5. Endpoints
var usDollars = CultureInfo.GetCultureInfo("en-US");
app.MapGet("/orders", (CorrelationContext correlation) =>
    new { correlation.CorrelationId, Orders = SampleOrders.All });
app.MapGet("/orders/fail", string () => throw new InvalidOperationException("Payment gateway timed out"));
app.MapGet("/admin/report", (HttpContext context) =>
    $"Q4 2026 report for {context.User.Identity!.Name}: {SampleOrders.All.Sum(o => o.Total).ToString("C", usDollars)}")
    .RequireAuthorization();

app.Run();

record Order(int Id, string Customer, string City, decimal Total);

static class SampleOrders
{
    public static readonly Order[] All =
    [
        new(1042, "Jenna Morales", "Austin, TX", 84.50m),
        new(1043, "Tyler Brooks", "Columbus, OH", 129.99m),
        new(1044, "Rachel Kim", "Seattle, WA", 42.25m),
    ];
}

The three orders are a C# record, and the report total uses a LINQ Sum formatted as en-US dollars. The demo authentication handler (ApiKeyHandler.cs) is deliberately tiny:

using System.Security.Claims;
using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Authentication;
using Microsoft.Extensions.Options;

namespace OrdersApi;

// Demo only: a fixed API key. Use a real identity provider in production.
public class ApiKeyHandler(IOptionsMonitor<AuthenticationSchemeOptions> options, ILoggerFactory logger, UrlEncoder encoder)
    : AuthenticationHandler<AuthenticationSchemeOptions>(options, logger, encoder)
{
    public const string SchemeName = "ApiKey";

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue("X-Api-Key", out var key))
            return Task.FromResult(AuthenticateResult.NoResult());
        if (key != "demo-key-2026")
            return Task.FromResult(AuthenticateResult.Fail("Invalid API key"));

        var identity = new ClaimsIdentity([new Claim(ClaimTypes.Name, "jenna.morales")], SchemeName);
        var ticket = new AuthenticationTicket(new ClaimsPrincipal(identity), SchemeName);
        return Task.FromResult(AuthenticateResult.Success(ticket));
    }
}

Note: WebApplication adds UseRouting, UseAuthentication and UseAuthorization for you when you don’t call them, right at the start of the pipeline. Call them yourself, as above, when middleware like UseCorrelationId must come after them.

Test the Request Timing and Correlation ID Middleware

With the API running in the background, this client sends six requests and prints the status and both headers. It’s a plain HttpClient in C# call per line:

var http = new HttpClient { BaseAddress = new Uri("http://localhost:5790") };

async Task Call(string path, string? apiKey = null, string? correlationId = null)
{
    var request = new HttpRequestMessage(HttpMethod.Get, path);
    if (apiKey is not null) request.Headers.Add("X-Api-Key", apiKey);
    if (correlationId is not null) request.Headers.Add("X-Correlation-ID", correlationId);
    var res = await http.SendAsync(request);
    string Header(string name) => res.Headers.TryGetValues(name, out var v) ? v.First() : "-";
    Console.WriteLine($"{path,-15}{(int)res.StatusCode,-5}id={Header("X-Correlation-ID"),-15}{Header("X-Response-Time-ms")} ms");
}

await Call("/orders");
await Call("/orders", correlationId: "order-1042-tx");
await Call("/admin/report");
await Call("/admin/report", apiKey: "demo-key-2026");
await Call("/wp-login.php");
await Call("/orders/fail");

Output:

/orders        200  id=701240978db2   45 ms
/orders        200  id=order-1042-tx  4 ms
/admin/report  401  id=-              5 ms
/admin/report  200  id=117c47a0bd4f   8 ms
/wp-login.php  404  id=-              0 ms
/orders/fail   500  id=-              22 ms

How does this work?

The first /orders call got a generated 12-character ID, and the second got back the order-1042-tx it sent. The timing header is on every single line because that middleware sits near the top.

/admin/report with no key returned 401 and no ID. Authorization stopped the request before it reached the correlation middleware, so the order decides which middleware sees a request.

With the key it returned 200 (Q4 2026 report for jenna.morales: $256.74), and /wp-login.php got 404 from the bot blocker.

So here’s the catch: /orders/fail returned 500 without its correlation ID. The exception handler clears the response before it writes the error, but the timing header survived because OnStarting runs later.

Here’s the same /orders call through curl, with the headers:

curl.exe -i -H "X-Correlation-ID: order-1042-tx" http://localhost:5790/orders

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Kestrel
Transfer-Encoding: chunked
X-Correlation-ID: order-1042-tx
X-Response-Time-ms: 0

{"correlationId":"order-1042-tx","orders":[{"id":1042,"customer":"Jenna Morales","city":"Austin, TX","total":84.50},{"id":1043,"customer":"Tyler Brooks","city":"Columbus, OH","total":129.99},{"id":1044,"customer":"Rachel Kim","city":"Seattle, WA","total":42.25}]}

And the API’s own log for the /orders/fail request:

info: OrdersApi.Middleware.CorrelationIdMiddleware[0]
      4ad5e92245fb /orders/fail user=anonymous
info: OrdersApi.Middleware.RequestTimingMiddleware[0]
      GET /orders/fail -> 200 in 1 ms

Note: the timing log says /orders/fail -> 200, while the client got 500. The exception handler is outside the timing middleware, so it set the status code after timing had already logged.

How Do You Short-Circuit ASP.NET Core Middleware?

You short-circuit by not calling next, like the bot blocker in Program.cs: it sets 404 and returns. The rest of the pipeline is skipped, but middleware registered earlier still runs its after-next code.

A probe for /wp-admin/install.php got 404 with no routing, authentication or endpoint work at all. Built-in middleware does this too: static files end the pipeline when a file matches, and authorization returns 401 or 403 without calling the endpoint.

Common ASP.NET Core Middleware Mistakes

UseAuthorization before UseAuthentication

This is the order bug I see most, and my JWT authentication guide hit it too. I swapped the two lines in the same Program.cs:

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

A request with the valid key now got 401 Unauthorized. Authorization ran first and saw an anonymous user, because authentication hadn’t set HttpContext.User yet. Put them back in that order: authentication, then authorization.

Changing headers after next() has started the response

This is the timing middleware written the obvious way, setting the header after the endpoint wrote its body:

#:sdk Microsoft.NET.Sdk.Web
using System.Diagnostics;

var builder = WebApplication.CreateBuilder();
builder.Logging.ClearProviders();
var app = builder.Build();

app.Use(async (context, next) =>
{
    var timer = Stopwatch.StartNew();
    await next(context);
    try
    {
        context.Response.Headers["X-Response-Time-ms"] = timer.ElapsedMilliseconds.ToString();
    }
    catch (InvalidOperationException ex)
    {
        Console.WriteLine($"HasStarted = {context.Response.HasStarted}");
        Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
    }
});
app.Run(context => context.Response.WriteAsync("3 open orders"));

app.Urls.Add("http://localhost:5790");
await app.StartAsync();
var res = await new HttpClient().GetAsync("http://localhost:5790/");
Console.WriteLine($"Client got {(int)res.StatusCode}, timing header sent: {res.Headers.Contains("X-Response-Time-ms")}");
await app.StopAsync();

Output:

HasStarted = True
InvalidOperationException: Headers are read-only, response has already started.
Client got 200, timing header sent: False

The client still got 200, so this bug hides easily. Check context.Response.HasStarted before touching headers, or register them in OnStarting like Method 3 does.

Which ASP.NET Core Middleware Approach Should You Use?

I’d pick a convention-based class with a UseXxx extension for most shared middleware, and IMiddleware when you need a DbContext in the constructor.

Things to Keep in Mind

• Exception handler first. It only catches what runs after it, so register it before everything else.
• Authentication before authorization. Swapping them returned 401 for a valid key in my test.
• Headers before the body. Set them before next or in OnStarting; after the response starts they’re read-only.
• Mind the automatic calls. Call UseRouting and the auth middleware yourself when your own middleware must sit between them.

These pages pair well with this one:

• All ASP.NET Core tutorials on AspDotnetHelp
• Build an ASP.NET Core Web API with EF Core
• Add OpenAPI and Scalar to ASP.NET Core
• Upgrade an app from .NET 8 to .NET 10

Frequently Asked Questions

C# pattern matching tests a value’s type, ranges and properties in one expression with is or a switch expression, and the compiler warns you about cases you forgot.

Quick answer: use x is Type t for one check and a switch expression for a rule set. I ran everything below on .NET 10 against the same store orders.

decimal Shipping(Order order) => order switch
{
    { Total: >= 100m } => 0m,
    { ShipTo.State: "AK" or "HI" } => 24.99m,
    { WeightLbs: > 50 } => 89.00m,
    _ => 7.99m
};

What Is Pattern Matching in C#?

A pattern is a test you write on the right side of is, after case in a switch statement, or on the left of => in a switch expression. If the value matches, you can also capture parts of it into new variables.

Each kind arrived in a different C# version. On .NET 10 (C# 14) you get all of them:

New file-based apps target the latest language version, so every sample here is a single .cs file you start with dotnet run. If that’s new to you, read my guide to dotnet run file-based apps first.

Type Patterns and Declaration Patterns with is

The store accepts several payment shapes, and they arrive as object. A declaration pattern checks the runtime type and gives you a typed variable in one step:

using System.Globalization;
CultureInfo.CurrentCulture = new("en-US");

object?[] payments = [49.99m, "PAYPAL-7781", 120, null, new Card("Visa", "4242")];
foreach (object? p in payments)
    Console.WriteLine(Describe(p));

static string Describe(object? payment)
{
    if (payment is null) return "No payment on file";
    if (payment is decimal amount) return $"Cash {amount:C}";
    if (payment is string code && code.StartsWith("PAYPAL"))
        return $"PayPal ref {code[7..]}";
    if (payment is Card card) return $"{card.Brand} ending {card.Last4}";
    return $"Unknown: {payment.GetType().Name}";
}
record Card(string Brand, string Last4);

Output:

Cash $49.99
PayPal ref 7781
Unknown: Int32
No payment on file
Visa ending 4242

The 120 printed Unknown: Int32. A boxed int doesn’t match decimal, because the pattern only unboxes to the exact type. That’s the same rule behind boxing and unboxing in C#.

Before C# 7 you’d write as plus a null check, or a cast that throws. My type casting in C# post compares those; for type tests, I always use is now.

Two details I lean on: amount only exists where the match succeeded, and code.StartsWith runs only after code is known to be a string, thanks to &&.

Null Checks with Pattern Matching: is null and is not null

Microsoft Learn guarantees that x is null never calls a user-overloaded ==. Here’s why that matters, with a product SKU class whose == treats a blank code as null:

var blank = new Sku("");
Sku? missing = null;

Console.WriteLine($"blank == null:       {blank == null}");
Console.WriteLine($"blank is null:       {blank is null}");
Console.WriteLine($"missing is not null: {missing is not null}");

if (FindSku("TENT-2P") is { } sku)
    Console.WriteLine($"Found {sku.Code}");

static Sku? FindSku(string code) => code == "TENT-2P" ? new Sku(code) : null;

class Sku(string code)
{
    public string Code => code;
    public static bool operator ==(Sku? a, Sku? b) => (a?.Code ?? "") == (b?.Code ?? "");
    public static bool operator !=(Sku? a, Sku? b) => !(a == b);
    public override bool Equals(object? o) => o is Sku s && s.Code == Code;
    public override int GetHashCode() => Code.GetHashCode();
}

Output:

blank == null:       True
blank is null:       False
missing is not null: False
Found TENT-2P

The overloaded operator said a real object equals null. is null ignored it and told the truth. is not null is the readable way to write the opposite.

The last line uses the empty property pattern is { } sku: it matches any non-null value and declares the variable. More null techniques are in how to check for null values in C#.

Pattern Matching Switch Expressions with Relational and Logical Patterns

Same store, now pricing by state and package weight. Constant patterns match exact values, relational patterns (<, <=, >, >=) match ranges, and and, or, not combine them:

foreach (var s in new[] { "CA", "TX", "NY", "AK" })
    Console.WriteLine($"{s}: {Zone(s)}");
foreach (var lbs in new[] { 0.5, 4, 25, 80 })
    Console.WriteLine($"{lbs} lb: {Rate(lbs)}");

static string Zone(string state) => state switch
{
    "CA" or "OR" or "WA" => "West",
    "AK" or "HI" => "Noncontiguous",
    not ("TX" or "OK") => "Standard",
    _ => "South"
};

static string Rate(double lbs) => lbs switch
{
    <= 0 => throw new ArgumentOutOfRangeException(nameof(lbs)),
    < 1 => "$4.99 envelope",
    >= 1 and < 20 => "$8.99 ground",
    >= 20 and <= 70 => "$19.99 heavy",
    _ => "freight quote"
};

Output:

CA: West
TX: South
NY: Standard
AK: Noncontiguous
0.5 lb: $4.99 envelope
4 lb: $8.99 ground
25 lb: $19.99 heavy
80 lb: freight quote

Arms run top to bottom and the first match wins. That’s why TX reached the discard _: the not ("TX" or "OK") arm sent every other state to Standard first.

The right side of a relational pattern must be a constant, so you can’t write < maxWeight with a variable. Use a when guard for that (below).

A switch expression returns a value; the classic statement runs code. If you still use case labels and break, my switch case in C# guide covers both side by side.

Property Patterns and Extended Property Patterns

This is the code from the top of the post, run on four sample orders. A property pattern checks properties or fields against nested patterns, and it never matches null:

using System.Globalization;
CultureInfo.CurrentCulture = new("en-US");

Order[] orders =
[
    new(1001, 142.50m, 12, new("Denver", "CO")),
    new(1002, 38.00m, 3, new("Anchorage", "AK")),
    new(1003, 64.25m, 58, new("Austin", "TX")),
    new(1004, 19.99m, 1, new("Columbus", "OH")),
];
foreach (var o in orders)
    Console.WriteLine($"#{o.Id} {o.ShipTo.State}: {Shipping(o):C}");

static decimal Shipping(Order order) => order switch
{
    { Total: >= 100m } => 0m,
    { ShipTo.State: "AK" or "HI" } => 24.99m,
    { WeightLbs: > 50 } => 89.00m,
    _ => 7.99m
};
record Address(string City, string State);
record Order(int Id, decimal Total, double WeightLbs, Address ShipTo);

Output:

#1001 CO: $0.00
#1002 AK: $24.99
#1003 TX: $89.00
#1004 OH: $7.99

ShipTo.State is an extended property pattern (C# 10). It’s the short form of { ShipTo: { State: "AK" or "HI" } }, and Visual Studio’s IDE0170 rule suggests it.

Order matters here too. A $150 Alaska order ships free, because the free-shipping arm comes first. If Alaska should always pay, move that arm up.

These are positional records, so the property names come from the constructor. Why I use records for orders is in record vs class vs struct in C#.

Positional Patterns with Records, Tuples and Deconstruct

A positional pattern calls Deconstruct and matches each value in order. Records generate it; a class or struct can write its own. Tuples work too, which lets one switch test two inputs at once:

using System.Globalization;
CultureInfo.CurrentCulture = new("en-US");

var dock = new Address("Denver", "CO", "80202");
Console.WriteLine($"Ships from Denver: {dock is ("Denver", _, _)}");

Console.WriteLine(Tax("OR", 200m));
Console.WriteLine(Tax("WA", 200m));
Console.WriteLine(Tax("IL", 0m));

var box = new Package(14, 10, 6);
Console.WriteLine(box switch
{
    (> 24, _, _) or (_, > 24, _) => "Oversize",
    (_, _, <= 6) => "Fits the flat-rate box",
    _ => "Standard box"
});

static string Tax(string state, decimal subtotal) => (state, subtotal) switch
{
    (_, <= 0m) => "Nothing to tax",
    ("AK" or "DE" or "MT" or "NH" or "OR", _) => $"{state}: no state sales tax",
    ("WA", _) => $"WA 6.5%: {subtotal * 0.065m:C}",
    _ => $"{state}: look up the rate"
};

record Address(string City, string State, string Zip);
class Package(int length, int width, int height)
{
    public void Deconstruct(out int l, out int w, out int h) => (l, w, h) = (length, width, height);
}

Output:

Ships from Denver: True
OR: no state sales tax
WA 6.5%: $13.00
Nothing to tax
Fits the flat-rate box

The tuple switch is my favorite trick for tax and pricing tables. The five states with no state sales tax sit in one or arm, and Washington’s 6.5% on $200 came out to $13.00.

The Package class has no properties at all, just a Deconstruct method, and (_, _, <= 6) still read its height. The pattern’s order must match the out parameters. Tuples themselves are covered in tuples in C#.

var Pattern, Discards and when Guards in a Switch Statement

Patterns also work after case. A when guard adds any Boolean condition, including ones that use variables, and var (name, total, items) deconstructs the tuple into locals for it:

using System.Globalization;
CultureInfo.CurrentCulture = new("en-US");

var carts = new (string Customer, decimal Total, int Items)[]
{
    ("Jenna Morales", 250m, 6), ("Tyler Brooks", 40m, 1), ("Ava Chen", 95m, 12)
};
foreach (var cart in carts)
{
    switch (cart)
    {
        case { Total: >= 200m }:
            Console.WriteLine($"{cart.Customer}: free gift"); break;
        case var (name, total, items) when total / items < 10m:
            Console.WriteLine($"{name}: bulk deal, {total / items:C} per item"); break;
        default:
            Console.WriteLine($"{cart.Customer}: no promo"); break;
    }
}

Output:

Jenna Morales: free gift
Tyler Brooks: no promo
Ava Chen: bulk deal, $7.92 per item

Ava Chen’s cart is $95 for 12 items, so the guard computed $7.92 per item and gave her the bulk deal. Tyler Brooks matched neither case and hit default.

The discard _ matches anything, including null, but only in a switch expression. In is or a switch statement you write var _ or default instead.

List Patterns and Slice Patterns (C# 11+)

List patterns match arrays, lists and anything with a Length or Count plus an indexer. Same store, now reading package tracking histories:

string[][] histories =
[
    [],
    ["Created"],
    ["Created", "Shipped", "Delivered"],
    ["Created", "Shipped", "Returned", "Refunded"],
    ["Created", "Shipped", "In transit", "In transit", "Delivered"],
];
foreach (var h in histories)
    Console.WriteLine(Track(h));

static string Track(string[] events) => events switch
{
    [] => "No events yet",
    [var only] => $"Only: {only}",
    ["Created", .. var middle, "Delivered"] => $"Delivered, {middle.Length} scan(s) between",
    [.., "Refunded"] => "Refunded",
    [_, _, ..] => "Still moving"
};

Output:

No events yet
Only: Created
Delivered, 1 scan(s) between
Refunded
Delivered, 3 scan(s) between

.. is the slice pattern. It matches zero or more elements, you get one per list pattern, and .. var middle captured the scans between Created and Delivered: 1 for the short trip, 3 for the long one.

[] matches an empty array and [var only] exactly one element. The same syntax works on a List<T> in C#, and on strings, since a string has Length and an indexer.

Why Does a Switch Expression Warn CS8509 (and Error CS8510)?

A switch expression must return something for every input. Leave a value out and you get a compiler warning, plus an exception at run time. Here’s an order-status label with Canceled missing:

using System.Runtime.CompilerServices;

foreach (var status in new[] { "Paid", "Shipped", "Canceled" })
{
    try { Console.WriteLine(Label(status)); }
    catch (SwitchExpressionException ex)
    {
        Console.WriteLine($"{ex.GetType().Name}: {ex.UnmatchedValue}");
    }
}

static string Label(string status) => status switch
{
    "Paid" => "Ready to pack",
    "Shipped" => "On the truck",
};

Output:

C:\DotNetDemo\PatternMatching\Exhaustive.cs(12,46): warning CS8509: The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern '""' is not covered.
Ready to pack
On the truck
SwitchExpressionException: Canceled

The build printed CS8509 and the program still ran. Canceled threw SwitchExpressionException, whose UnmatchedValue told me exactly what slipped through.

I’d treat that warning as an error. Catching the exception is only for the demo; try-catch in C# explains when catching is right.

With an enum, handling every named member still leaves a gap: I got CS8524, because (Status)2 is a legal value. Add a discard arm that throws. The enum in C# post shows why casts create those values.

The opposite problem is an arm that can never run. Putting < 20 before < 1 gave error CS8510: “The pattern is unreachable.” Order arms from the most specific to the most general.

Common Pattern Matching Mistakes and How to Fix Them

The worst one is precedence: not binds tighter than and, which binds tighter than or. Here’s a quantity check that looks right:

Console.WriteLine($"Qty 7 outside 1-5 (bug): {OutsideBug(7)}");
Console.WriteLine($"Qty 7 outside 1-5 (fix): {Outside(7)}");

object count = 3;
Console.WriteLine($"boxed int is long: {count is long}");
Console.WriteLine($"boxed int is int:  {count is int}");

static bool OutsideBug(int qty) => qty is not >= 1 and <= 5;
static bool Outside(int qty) => qty is not (>= 1 and <= 5);

Output:

C:\DotNetDemo\PatternMatching\Mistakes.cs(8,56): warning CS9336: The pattern is redundant.
Qty 7 outside 1-5 (bug): False
Qty 7 outside 1-5 (fix): True
boxed int is long: False
boxed int is int:  True

qty is not >= 1 and <= 5 means (not >= 1) and <= 5, so 7 came back False. Parentheses fixed it. On .NET 10 the compiler flagged the bug with CS9336: “The pattern is redundant.”

• Variables in patterns: qty is limit fails with CS9135 (“A constant value of type ‘int’ is expected”). Use qty == limit or a when guard.
• Boxed numbers: a boxed int isn’t a long, so count is long printed False. Match the exact type, then convert.
• Arm order: the first match wins, so put Total: >= 100m after the surcharge arm if Alaska should always pay.
• Null in property patterns: { } never matches null, so a null order falls to _. Add a null => throw arm if null means a bug.

Which C# Pattern Should You Use?

If you only learn one, learn the switch expression with property patterns. It replaces most if-else chains I see in code reviews, and C# keeps adding to it: what’s new in C# 14 lists the latest changes.

For the next step, these fit well with patterns:

• Filter orders with LINQ and pattern-based lambdas
• Interfaces you can match with type patterns
• Class hierarchies behind type switches
• Every C# tutorial on aspdotnethelp.com

Frequently Asked Questions

The only real difference is how long the container keeps an instance: per injection, per request, or for the life of the app.

On a .NET 10 minimal API, three requests kept the singleton at instance #1, gave each request its own scoped instance, and created a fresh transient on every injection.

Transient vs Scoped vs Singleton at a Glance

The instance numbers in this table come from the real run further down:

None of this changed in the .NET 10 release. Keyed registrations, covered below, arrived in .NET 8.

The Sample: An Order-Pricing API with a Sales-Tax Calculator

Every test runs on one project, PricingApi (SDK 10.0.402). It prices a US order with state sales tax using a singleton QuoteCounter, a scoped OrderPricingService and a transient SalesTaxCalculator.

Each class inherits Tracked, which numbers new instances per type (#1, #2, #3), so you can spot a repeat instantly. Here’s Services.cs:

using System.Collections.Concurrent;

namespace PricingApi;

// Every new instance gets the next number for its type: #1, #2, #3 ...
public abstract class Tracked : IDisposable
{
    static readonly ConcurrentDictionary<Type, int> created = new();
    public int Id { get; }
    protected Tracked() => Id = created.AddOrUpdate(GetType(), 1, (_, n) => n + 1);
    public void Dispose() => Console.WriteLine($"disposed {GetType().Name} #{Id}");
}

// Singleton: one per app, so it must be thread-safe
public class QuoteCounter : Tracked
{
    int count;
    public int Next() => Interlocked.Increment(ref count);
}

// Transient: small, stateless, cheap to create
public class SalesTaxCalculator : Tracked
{
    public decimal Tax(decimal subtotal, decimal rate) =>
        Math.Round(subtotal * rate, 2, MidpointRounding.AwayFromZero);
}

// Scoped: one per HTTP request
public class OrderPricingService(QuoteCounter counter, SalesTaxCalculator calculator) : Tracked
{
    public PriceQuote Quote(decimal subtotal, IStateSalesTax state)
    {
        var tax = calculator.Tax(subtotal, state.Rate);
        return new(counter.Next(), state.Code, subtotal, tax, subtotal + tax);
    }
}

public record PriceQuote(int QuoteNumber, string State, decimal Subtotal, decimal Tax, decimal Total);

// Keyed services: one implementation per state
public interface IStateSalesTax
{
    string Code { get; }
    decimal Rate { get; }
}

public class TexasSalesTax : IStateSalesTax
{
    public string Code => "TX";
    public decimal Rate => 0.0625m;
}

public class CaliforniaSalesTax : IStateSalesTax
{
    public string Code => "CA";
    public decimal Rate => 0.0725m;
}

The dependencies arrive through a primary constructor in C#, and PriceQuote is a positional record (my record vs class vs struct comparison explains that choice). Program.cs registers everything and maps the endpoints:

using PricingApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<QuoteCounter>();
builder.Services.AddScoped<OrderPricingService>();
builder.Services.AddTransient<SalesTaxCalculator>();
builder.Services.AddKeyedScoped<IStateSalesTax, TexasSalesTax>("TX");
builder.Services.AddKeyedScoped<IStateSalesTax, CaliforniaSalesTax>("CA");

var app = builder.Build();

// Middleware resolves the same services from the request scope
app.Use(async (context, next) =>
{
    var sp = context.RequestServices;
    context.Items["mw"] = Ids(sp.GetRequiredService<QuoteCounter>(),
        sp.GetRequiredService<OrderPricingService>(), sp.GetRequiredService<SalesTaxCalculator>());
    await next(context);
});

// The endpoint asks for the scoped and transient services twice
app.MapGet("/lifetimes", (HttpContext context, QuoteCounter singleton,
    OrderPricingService scoped1, OrderPricingService scoped2,
    SalesTaxCalculator transient1, SalesTaxCalculator transient2) =>
    $"middleware  {context.Items["mw"]}\n" +
    $"endpoint    singleton #{singleton.Id}   scoped #{scoped1.Id} #{scoped2.Id}   " +
    $"transient #{transient1.Id} #{transient2.Id}");

app.MapGet("/quote/tx", (decimal subtotal, [FromKeyedServices("TX")] IStateSalesTax tax,
    OrderPricingService pricing) => pricing.Quote(subtotal, tax));

app.MapGet("/quote/{state}", (string state, decimal subtotal, HttpContext context,
    OrderPricingService pricing) =>
    context.RequestServices.GetKeyedService<IStateSalesTax>(state.ToUpperInvariant()) is { } tax
        ? Results.Ok(pricing.Quote(subtotal, tax))
        : Results.NotFound($"No sales tax service registered for {state}"));

app.Run();

static string Ids(QuoteCounter s, OrderPricingService sc, SalesTaxCalculator t) =>
    $"singleton #{s.Id}   scoped #{sc.Id}      transient #{t.Id}";

The project needs no NuGet packages, since the container ships with ASP.NET Core. The launch profile pins port 5738 and Development:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5738",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

AddScoped vs AddTransient: How Many Instances in One Request?

With the API running, this file-based app calls /lifetimes three times and prints what the middleware and the endpoint received:

var api = new HttpClient { BaseAddress = new Uri("http://localhost:5738/") };

for (int i = 1; i <= 3; i++)
{
    Console.WriteLine($"Request {i}");
    Console.WriteLine(await api.GetStringAsync("lifetimes"));
}

Output:

Request 1
middleware  singleton #1   scoped #1      transient #2
endpoint    singleton #1   scoped #1 #1   transient #3 #4
Request 2
middleware  singleton #1   scoped #2      transient #6
endpoint    singleton #1   scoped #2 #2   transient #7 #8
Request 3
middleware  singleton #1   scoped #3      transient #10
endpoint    singleton #1   scoped #3 #3   transient #11 #12

In request 1, the endpoint asked for OrderPricingService twice and got #1 #1, the same object the middleware saw. It asked for SalesTaxCalculator twice and got #3 #4.

Transient #1 went into the OrderPricingService constructor, so each request built four calculators but one pricing service. That’s the addscoped vs addtransient difference: scoped shares within a request, transient never shares.

Singleton vs Scoped: What Changes Between Requests?

Same PricingApi run, read across the requests: the singleton stayed #1 all three times, while the scoped service went #1, #2, #3. ASP.NET Core creates a scope per request and disposes it after the response.

Middleware is where you can trip. Resolve scoped services in InvokeAsync or from RequestServices, as mine does, never in a middleware constructor, which runs once and turns them into singletons.

Anything about the current user, like the claims in my JWT authentication guide, belongs in scoped services for the same reason.

Transient vs Scoped vs Singleton in a Console App with CreateScope

A console app has no requests, so you create the scopes with CreateScope. This generic host (Microsoft.Extensions.Hosting 10.0.14) does what ASP.NET Core does per request:

#:package Microsoft.Extensions.Hosting@10.0.14
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddSingleton<QuoteCounter>();
builder.Services.AddScoped<OrderPricing>();
builder.Services.AddTransient<TaxCalculator>();
using var host = builder.Build();

for (int i = 1; i <= 2; i++)
{
    using var scope = host.Services.CreateScope();
    Console.WriteLine($"Scope {i}");
    Show<QuoteCounter>(scope.ServiceProvider);
    Show<OrderPricing>(scope.ServiceProvider);
    Show<TaxCalculator>(scope.ServiceProvider);
}

// Resolve T twice from the same provider and print both ids
static void Show<T>(IServiceProvider sp) where T : Tracked
{
    var a = sp.GetRequiredService<T>();
    var b = sp.GetRequiredService<T>();
    Console.WriteLine($"  {typeof(T).Name}: #{a.Id} #{b.Id}");
}

abstract class Tracked
{
    static readonly Dictionary<Type, int> made = [];
    public int Id { get; }
    protected Tracked() =>
        Id = made[GetType()] = made.GetValueOrDefault(GetType()) + 1;
}

class QuoteCounter : Tracked;
class OrderPricing : Tracked;
class TaxCalculator : Tracked;

Output:

Scope 1
  QuoteCounter: #1 #1
  OrderPricing: #1 #1
  TaxCalculator: #1 #2
Scope 2
  QuoteCounter: #1 #1
  OrderPricing: #2 #2
  TaxCalculator: #3 #4

Same pattern as the API: QuoteCounter is #1 in both scopes, OrderPricing repeats inside a scope (#1 #1, then #2 #2), and TaxCalculator is always new.

That’s all it takes to add dependency injection to a console app. Starting fresh? Set up a console app in VS Code first.

When Are Transient, Scoped and Singleton Services Disposed?

Every sample class implements IDisposable, so the server log shows the cleanup at the end of request 1:

disposed SalesTaxCalculator #4
disposed SalesTaxCalculator #3
disposed SalesTaxCalculator #2
disposed OrderPricingService #1
disposed SalesTaxCalculator #1

The four transients and the scoped service were disposed when the request’s scope ended, newest first. The singleton lives until shutdown. You never call Dispose on something the container created.

The risky case is a disposable transient resolved from the root provider instead of a scope. This test resolves one inside a scope and three from the root:

#:package Microsoft.Extensions.DependencyInjection@10.0.14
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection().AddTransient<TaxCalculator>();
using (var root = services.BuildServiceProvider())
{
    using (var scope = root.CreateScope())
    {
        scope.ServiceProvider.GetRequiredService<TaxCalculator>();
        Console.WriteLine("Leaving the scope");
    }
    for (int i = 0; i < 3; i++) root.GetRequiredService<TaxCalculator>();
    Console.WriteLine("3 transients resolved from the root provider");
}
Console.WriteLine("Root provider disposed");

class TaxCalculator : IDisposable
{
    static int made;
    public int Id { get; } = ++made;
    public void Dispose() => Console.WriteLine($"  disposed TaxCalculator #{Id}");
}

Output:

Leaving the scope
  disposed TaxCalculator #1
3 transients resolved from the root provider
  disposed TaxCalculator #4
  disposed TaxCalculator #3
  disposed TaxCalculator #2
Root provider disposed

Important: #1 was disposed when its scope closed, but #2 to #4 lived until the root provider was disposed. Do that in a loop and you have a memory leak. My notes on Dispose and Finalize in C# cover the pattern itself.

Captive Dependency: A Scoped Service Inside a Singleton

A captive dependency is a longer-lived service holding a shorter-lived one. Here a singleton PriceCache takes a scoped ShoppingCart, and the host is built twice:

#:package Microsoft.Extensions.Hosting@10.0.14
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

foreach (var env in new[] { "Production", "Development" })
{
    var settings = new HostApplicationBuilderSettings();
    settings.EnvironmentName = env;
    var builder = Host.CreateApplicationBuilder(settings);
    builder.Services.AddSingleton<PriceCache>();  // singleton
    builder.Services.AddScoped<ShoppingCart>();   // scoped
    try
    {
        using var host = builder.Build();
        int first = Cart(host), second = Cart(host);
        Console.WriteLine($"{env}: cart #{first} then #{second}");
    }
    catch (AggregateException ex)
    {
        var inner = ex.InnerException!;
        Console.WriteLine($"{env}: {inner.GetType().Name}");
        Console.WriteLine(inner.Message);
    }
}

// One "request": a new scope that asks for the singleton
static int Cart(IHost host)
{
    using var scope = host.Services.CreateScope();
    var sp = scope.ServiceProvider;
    return sp.GetRequiredService<PriceCache>().Cart.Id;
}

class ShoppingCart
{
    static int made;
    public int Id { get; } = ++made;
}

class PriceCache(ShoppingCart cart)
{
    public ShoppingCart Cart => cart;
}

Output:

Production: cart #1 then #1
Development: InvalidOperationException
Error while validating the service descriptor 'ServiceType: PriceCache Lifetime: Singleton ImplementationType: PriceCache': Cannot consume scoped service 'ShoppingCart' from singleton 'PriceCache'.

Production “works,” and that’s the bug: both requests got cart #1, so one customer’s cart leaks into the next request. Development threw an InvalidOperationException (inside an AggregateException) at Build().

That’s scope validation: ValidateScopes and ValidateOnBuild are on by default in Development. Turn them on everywhere with builder.Host.UseDefaultServiceProvider(o => { o.ValidateScopes = true; o.ValidateOnBuild = true; }).

How Do You Use a Scoped Service from a Singleton or BackgroundService?

A BackgroundService is a singleton, so it can’t take a scoped service in its constructor. Inject IServiceScopeFactory and open a scope per unit of work:

#:package Microsoft.Extensions.Hosting@10.0.14
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.ClearProviders();
builder.Services.AddScoped<OrderPricing>();
builder.Services.AddHostedService<NightlyRepricer>();
await builder.Build().RunAsync();

class NightlyRepricer(IServiceScopeFactory scopes,
    IHostApplicationLifetime app) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        for (int batch = 1; batch <= 3; batch++)
        {
            await using var scope = scopes.CreateAsyncScope();
            var sp = scope.ServiceProvider;
            var pricing = sp.GetRequiredService<OrderPricing>();
            Console.WriteLine($"Batch {batch}: OrderPricing #{pricing.Id}");
        }
        app.StopApplication();
    }
}

class OrderPricing : Tracked;

abstract class Tracked : IDisposable
{
    static readonly Dictionary<Type, int> made = [];
    public int Id { get; }
    protected Tracked() => Id = made[GetType()] = made.GetValueOrDefault(GetType()) + 1;
    public void Dispose() => Console.WriteLine($"  disposed {GetType().Name} #{Id}");
}

Output:

Batch 1: OrderPricing #1
  disposed OrderPricing #1
Batch 2: OrderPricing #2
  disposed OrderPricing #2
Batch 3: OrderPricing #3
  disposed OrderPricing #3

Each batch got its own OrderPricing, disposed before the next. CreateAsyncScope with await using also handles IAsyncDisposable services; see async and await in C# for that syntax.

Thread Safety: The Real Cost of a Singleton

A singleton serves every request at once, so its fields are shared. This test hits one QuoteCounter 100,000 times from Parallel.For:

#:package Microsoft.Extensions.DependencyInjection@10.0.14
using Microsoft.Extensions.DependencyInjection;

using var sp = new ServiceCollection().AddSingleton<QuoteCounter>().BuildServiceProvider();

Parallel.For(0, 100_000, _ => sp.GetRequiredService<QuoteCounter>().Add());

var counter = sp.GetRequiredService<QuoteCounter>();
Console.WriteLine($"Expected 100000 | count++ {counter.Unsafe} | Interlocked {counter.Safe}");

class QuoteCounter
{
    int unsafeCount, safeCount;
    public int Unsafe => unsafeCount;
    public int Safe => safeCount;
    public void Add()
    {
        unsafeCount++;                          // read, add, write: two threads can collide
        Interlocked.Increment(ref safeCount);   // atomic
    }
}

Output:

Expected 100000 | count++ 55885 | Interlocked 100000

Plain count++ lost 44,115 increments because threads overwrote each other; Interlocked.Increment hit exactly 100,000. The container creates services safely, but your singleton’s own state needs Interlocked, a lock or a concurrent collection.

DbContext and HttpClient Lifetimes in ASP.NET Core

AddDbContext registers the context as scoped by default, one change tracker per request. Never put it in a singleton; my ASP.NET Core Web API with EF Core gets it per request.

Typed clients from AddHttpClient<T> are transient, and Learn warns against capturing one in a singleton (it stops seeing DNS changes). In a singleton, inject IHttpClientFactory and call CreateClient. More in my HttpClient in C# guide.

Keyed Services with AddKeyedScoped and [FromKeyedServices]

Keyed services (.NET 8+) register several implementations of one interface in C# under keys. /quote/tx picks Texas with [FromKeyedServices("TX")]; /quote/{state} picks at run time with GetKeyedService. Same PricingApi project, $120 subtotal:

curl.exe -s "http://localhost:5738/quote/tx?subtotal=120"
{"quoteNumber":1,"state":"TX","subtotal":120,"tax":7.50,"total":127.50}

curl.exe -s "http://localhost:5738/quote/ca?subtotal=120"
{"quoteNumber":2,"state":"CA","subtotal":120,"tax":8.70,"total":128.70}

curl.exe -i "http://localhost:5738/quote/fl?subtotal=120"
HTTP/1.1 404 Not Found
"No sales tax service registered for fl"

Texas (6.25%) added $7.50, California (7.25%) added $8.70, and Florida got a 404 because no key matched. Quote numbers 1 and 2 came from the one singleton counter.

GetService vs GetRequiredService, and TryAdd vs Add

This test adds Texas and California with Add, tries New York with TryAdd, then resolves a service nobody registered:

#:package Microsoft.Extensions.DependencyInjection@10.0.14
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;

var services = new ServiceCollection();
services.AddSingleton<IStateSalesTax, TexasSalesTax>();
services.AddSingleton<IStateSalesTax, CaliforniaSalesTax>();   // Add: appends a second registration
services.TryAddSingleton<IStateSalesTax, NewYorkSalesTax>();   // TryAdd: skipped, one already exists
using var sp = services.BuildServiceProvider();

Console.WriteLine($"Registrations: {services.Count}");
Console.WriteLine($"GetRequiredService<IStateSalesTax>: {sp.GetRequiredService<IStateSalesTax>().Code}");
Console.WriteLine($"GetServices<IStateSalesTax>: {string.Join(", ", sp.GetServices<IStateSalesTax>().Select(t => t.Code))}");
Console.WriteLine($"GetService<IShippingRate>: {sp.GetService<IShippingRate>()?.ToString() ?? "null"}");
try
{
    sp.GetRequiredService<IShippingRate>();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"GetRequiredService<IShippingRate>: {ex.Message}");
}

interface IShippingRate { }
interface IStateSalesTax { string Code { get; } }
class TexasSalesTax : IStateSalesTax { public string Code => "TX"; }
class CaliforniaSalesTax : IStateSalesTax { public string Code => "CA"; }
class NewYorkSalesTax : IStateSalesTax { public string Code => "NY"; }

Output:

Registrations: 2
GetRequiredService<IStateSalesTax>: CA
GetServices<IStateSalesTax>: TX, CA
GetService<IShippingRate>: null
GetRequiredService<IShippingRate>: No service for type 'IShippingRate' has been registered.

GetService returned null; GetRequiredService threw. I use GetRequiredService so a missing registration fails loudly. With two Adds, a single resolve returns the last one (CA), and TryAddSingleton skipped New York because the type was already registered.

When Should You Use Transient, Scoped or Singleton?

Ask what state the class holds and who may see it:

If you’re torn on a stateless class, transient and scoped both work. Pick singleton only when there’s no per-request data and you’ve made it thread-safe.

More ASP.NET Core and C# guides from the site:

• All ASP.NET Core tutorials on AspDotnetHelp
• Upgrade a project from .NET 8 to .NET 10
• .NET Core interview questions and answers
• Learn C# from the ground up

Lifetimes matter most in two places I see go wrong all the time. Factory-based IMiddleware lets you inject scoped services safely, which I cover in custom middleware in ASP.NET Core, and a client like BlobServiceClient is a good singleton, as shown in Azure Blob Storage in C#.

Frequently Asked Questions

The built-in answer is Blazor QuickGrid, Microsoft’s free grid component. Give it an IQueryable, mark columns Sortable, add a Paginator and a bound search box, and you’re done. Here’s what we’re building on .NET 10:

Before You Start with Blazor QuickGrid

You need the .NET 10 SDK (I used 10.0.402; check your .NET version first) and any editor. If Blazor itself is new to you, my Blazor tutorial for beginners covers pages and components.

Our sample data is 200 made-up orders from 2026. Each order has these fields:

Step 1: Create the Blazor App and Add the QuickGrid Package

QuickGrid ships as its own NuGet package. Create a Blazor Web App and add it (10.0.14 was the current version on November 1, 2026):

dotnet new blazor -o QuickGridDemo
cd QuickGridDemo
dotnet add package Microsoft.AspNetCore.Components.QuickGrid --version 10.0.14

I deleted the two appsettings files (this demo doesn’t need them) and trimmed Properties/launchSettings.json to one http profile on port 5737:

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5737",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

My PC isn’t set to US regional settings, so I pinned the app to en-US at the top of Program.cs. Without it, Format="C" would print the local currency:

using System.Globalization;
using QuickGridDemo.Components;

// Show prices and dates the US way, whatever the server's regional settings are
CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

The project targets net10.0, the .NET 10 LTS release. Its full project file is in the EF Core section, after all three packages are added.

Step 2: Add the Order Model and 200 Sample Orders

Create Models/Order.cs. It’s a class, not a record, because Step 6 changes Status in place:

namespace QuickGridDemo.Models;

public class Order
{
    public int Id { get; set; }
    public string Customer { get; set; } = "";
    public string State { get; set; } = "";
    public DateOnly OrderDate { get; set; }
    public decimal Total { get; set; }
    public string Status { get; set; } = "Pending";
}

Then Services/OrderData.cs builds the orders. A fixed Random seed returns the same List of orders on every run, so your numbers will match mine:

using QuickGridDemo.Models;

namespace QuickGridDemo.Services;

public static class OrderData
{
    private static readonly string[] First = ["Jenna", "Tyler", "Maria", "Derek", "Ashley", "Marcus", "Kayla", "Brandon", "Lauren", "Caleb"];
    private static readonly string[] Last = ["Morales", "Brooks", "Bennett", "Hayes", "Foster", "Coleman", "Reed", "Parker", "Sullivan", "Grant"];
    private static readonly string[] States = ["CA", "TX", "NY", "FL", "WA", "IL", "CO", "GA"];
    private static readonly string[] Statuses = ["Pending", "Shipped", "Delivered", "Cancelled"];

    // Same seed = the same orders on every run
    public static List<Order> Create(int count, int seed = 2026)
    {
        var rng = new Random(seed);
        var start = new DateOnly(2026, 1, 1);
        return Enumerable.Range(1, count).Select(i => new Order
        {
            Id = 1000 + i,
            Customer = $"{First[rng.Next(First.Length)]} {Last[rng.Next(Last.Length)]}",
            State = States[rng.Next(States.Length)],
            OrderDate = start.AddDays(rng.Next(0, 300)),
            Total = Math.Round((decimal)(rng.NextDouble() * 2400 + 25), 2),
            Status = Statuses[rng.Next(Statuses.Length)]
        }).ToList();
    }
}

Step 3: Render Your First QuickGrid with PropertyColumn

Create Components/Pages/Orders.razor. Items takes an IQueryable<Order>, and each PropertyColumn shows one property:

@page "/orders"
@rendermode InteractiveServer
@using Microsoft.AspNetCore.Components.QuickGrid
@using QuickGridDemo.Models
@using QuickGridDemo.Services

<PageTitle>Orders</PageTitle>

<h1>2026 Orders</h1>

<QuickGrid Items="orders">
    <PropertyColumn Property="@(o => o.Id)" />
    <PropertyColumn Property="@(o => o.Customer)" />
    <PropertyColumn Property="@(o => o.State)" />
    <PropertyColumn Property="@(o => o.OrderDate)" />
    <PropertyColumn Property="@(o => o.Total)" />
    <PropertyColumn Property="@(o => o.Status)" />
</QuickGrid>

@code {
    private IQueryable<Order> orders = OrderData.Create(200).AsQueryable();
}

Don’t skip @rendermode InteractiveServer. Microsoft Learn says QuickGrid needs an interactive render mode for sorting and paging, which my Blazor render modes guide explains in detail.

Checkpoint: you should see a long, plain table. curl returned 200 with 201 <tr> rows (header + 200 orders), and the first row reads 1001 | Tyler Bennett | GA | 10/26/2026 | 2223.74 | Pending.

Step 4: Format QuickGrid Currency and Dates and Set a Default Sort

Raw 2223.74 isn’t money yet. Replace the columns with these (the Status column stays for now):

    <PropertyColumn Property="@(o => o.Id)" Title="Order #" Sortable="true" />
    <PropertyColumn Property="@(o => o.Customer)" Sortable="true" />
    <PropertyColumn Property="@(o => o.State)" Sortable="true" />
    <PropertyColumn Property="@(o => o.OrderDate)" Title="Order Date" Format="MMM d, yyyy" Sortable="true"
                    IsDefaultSortColumn="true" InitialSortDirection="SortDirection.Descending" />
    <PropertyColumn Property="@(o => o.Total)" Format="C" Sortable="true" Align="Align.Right" Class="total" />

Format works on any IFormattable type, so "C" gives US dollars, the same format string from formatting numbers with commas in C#. Title renames a header, and Align.Right lines up the cents.

IsDefaultSortColumn plus InitialSortDirection="SortDirection.Descending" puts the newest orders on top. The date pattern works like any DateTime format string in C#.

Step 5: Sort QuickGrid Columns by Clicking a Header

Every column in Step 4 already has Sortable="true", so each header is now a button. Click Total once for ascending and again for descending.

In headless Edge, the first click put $35.56 (order 1168) on top. The second click gave $2,416.01, order 1051 from CA. The header’s aria-sort switched from ascending to descending.

Checkpoint: after two clicks on Total, you see $2,416.01, $2,411.95 and $2,395.34 at the top.

Step 6: Add a QuickGrid TemplateColumn with a Status Badge and a Button

A TemplateColumn renders any markup you like, with the row in context. Swap the Status PropertyColumn for these two columns:

    <TemplateColumn Title="Status" SortBy="byStatus">
        <span class="badge @BadgeCss(context.Status)">@context.Status</span>
    </TemplateColumn>
    <TemplateColumn Title="Action">
        @if (context.Status == "Pending")
        {
            <button class="btn btn-sm btn-outline-primary ship" @onclick="@(() => Ship(context))">Ship</button>
        }
    </TemplateColumn>

Template columns can’t guess how to sort, so SortBy takes a GridSort<Order>. Change the grid to Items="orders.AsQueryable()" and add this to @code:

    private readonly List<Order> orders = OrderData.Create(200);
    private readonly GridSort<Order> byStatus = GridSort<Order>.ByAscending(o => o.Status);

    private void Ship(Order order) => order.Status = "Shipped";

    private static string BadgeCss(string status) => status switch
    {
        "Pending" => "text-bg-warning",
        "Shipped" => "text-bg-primary",
        "Delivered" => "text-bg-success",
        _ => "text-bg-secondary"
    };

The badge color comes from a C# switch expression. I clicked the first Ship button, on order 1016, and its row changed to 1016 | Kayla Brooks | NY | Oct 27, 2026 | $189.37 | Shipped.

Step 7: Add a QuickGrid Filter with a Search Box and a State Dropdown

QuickGrid has no filter row. You filter the IQueryable yourself and hand the result to Items. Add this markup above the grid:

<div class="d-flex gap-2 mb-2" style="max-width: 36rem;">
    <input id="search" class="form-control" placeholder="Search customer"
           @bind="search" @bind:event="oninput" />
    <select id="state" class="form-select" @bind="state">
        <option value="">All states</option>
        @foreach (var s in States)
        {
            <option value="@s">@s</option>
        }
    </select>
</div>

<p id="summary">@Filtered.Count() orders</p>

Then point the grid at Items="Filtered" and add the fields. Filtered is plain LINQ Where over the list:

    private static readonly string[] States = ["CA", "CO", "FL", "GA", "IL", "NY", "TX", "WA"];
    private string search = "";
    private string state = "";

    private IQueryable<Order> Filtered => orders.AsQueryable()
        .Where(o => o.Customer.Contains(search, StringComparison.OrdinalIgnoreCase))
        .Where(o => state == "" || o.State == state);

@bind:event="oninput" filters on every keystroke, and StringComparison.OrdinalIgnoreCase makes “brooks” match “Brooks” (more on Contains checks in C#).

The summary went from 200 orders to 22 orders after typing “brooks”, then 5 orders with TX picked.

Checkpoint: “brooks” + TX leaves 5 rows, starting with Tyler Brooks.

Step 8: Add QuickGrid Pagination with Paginator

Paging needs a PaginationState with ItemsPerPage, the grid’s Pagination parameter and a <Paginator> under it:

<QuickGrid Items="Filtered" Pagination="pagination">
    ...
</QuickGrid>

<Paginator State="pagination" />

    private readonly PaginationState pagination = new() { ItemsPerPage = 10 };

    // Back to page 1 whenever the filter changes
    private Task ResetPage() => pagination.SetCurrentPageIndexAsync(0);

Why ResetPage? A filter shrinks the list, and a reader on page 3 should land back on page 1 instead of a page that may no longer exist. So both inputs get @bind:after="ResetPage":

@bind="search" @bind:event="oninput" @bind:after="ResetPage"
@bind="state" @bind:after="ResetPage"

I went to page 3 and typed “a”: the pager went from 200 items Page 3 of 20 to 185 items Page 1 of 19. SetCurrentPageIndexAsync returns a Task, the kind of method my async/await guide covers.

Checkpoint: your pager reads 200 items Page 1 of 20, and one click on next shows 200 items Page 2 of 20 starting at order 1157.

Step 9: Style the QuickGrid with Class, CSS Isolation and Alignment

Out of the box, QuickGrid renders a bare table. Wrap it in a div and give it Bootstrap classes through Class:

<div class="grid">
<QuickGrid Items="Filtered" Pagination="pagination" Class="table table-sm align-middle">
    ...
</QuickGrid>
</div>

In the browser, the table’s class became quickgrid table table-sm align-middle, and it kept theme="default", the Theme value QuickGrid’s built-in styles match.

For your own rules, add Components/Pages/Orders.razor.css. The grid is a child component, so isolated CSS needs ::deep to reach its cells:

.grid ::deep table {
    min-width: 52rem;
}

.grid ::deep thead th {
    background: #eef2f7;
}

.grid ::deep td.total {
    font-variant-numeric: tabular-nums;
    font-weight: 600;
}

.grid ::deep tr.picked > td {
    background: #fff4d6;
}

td.total works because the column’s Class="total" lands on its header and every cell. Align.Right added col-justify-right to the same th.

Step 10: Select QuickGrid Rows with a Checkbox TemplateColumn

QuickGrid in .NET 10 has no built-in row selection (a row click event, OnRowClick, only shows up in the .NET 11 docs). A checkbox TemplateColumn and a HashSet do the job.

Add a first column to the grid, plus RowClass="RowCss" on the <QuickGrid> tag. RowClass, new in .NET 10, adds a CSS class to each row you return one for:

    <TemplateColumn Title="Pick">
        <input type="checkbox" checked="@selected.Contains(context.Id)"
               @onchange="@(() => Toggle(context.Id))" />
    </TemplateColumn>

Then change the summary line and add the selection code to @code. The picked class is the pale yellow rule from Step 9’s CSS file:

<p id="summary">@Filtered.Count() orders, @selected.Count selected (@SelectedTotal.ToString("C"))</p>

    private readonly HashSet<int> selected = [];

    private decimal SelectedTotal => orders.Where(o => selected.Contains(o.Id)).Sum(o => o.Total);

    private void Toggle(int id)
    {
        if (!selected.Remove(id)) selected.Add(id);
    }

    private string? RowCss(Order order) => selected.Contains(order.Id) ? "picked" : null;

Selection is by order Id, so it survives paging. After ticking rows 2 and 4, the summary read 200 orders, 2 selected ($2,259.30), and still 200 orders, 2 selected ($2,259.30) after a trip to page 2.

Checkpoint: when you tick two rows, they turn pale yellow and the summary shows 200 orders, 2 selected ($2,259.30).

Test the Blazor QuickGrid

Here’s every check I ran on the finished page in headless Edge, with real clicks and typing:

The empty rows on the last page are on purpose. Learn says the Paginator pads the final page so rows keep the same height on every page.

Virtualize QuickGrid for 10,000 Rows

If you have thousands of rows, paging isn’t your only option. Virtualize="true" renders only the rows near the scroll position. Set ItemSize to your row height in pixels and keep every row the same height:

@page "/orders-virtual"
@rendermode InteractiveServer
@using Microsoft.AspNetCore.Components.QuickGrid
@using QuickGridDemo.Models
@using QuickGridDemo.Services

<PageTitle>10,000 orders</PageTitle>

<h1>10,000 orders, virtualized</h1>

<div class="virtual-grid" style="height: 420px; overflow-y: auto;">
    <QuickGrid Items="orders" Virtualize="true" ItemSize="35" Class="table table-sm">
        <PropertyColumn Property="@(o => o.Id)" Title="Order #" Sortable="true" />
        <PropertyColumn Property="@(o => o.Customer)" Sortable="true" />
        <PropertyColumn Property="@(o => o.State)" Sortable="true" />
        <PropertyColumn Property="@(o => o.Total)" Format="C" Sortable="true" Align="Align.Right" />
    </QuickGrid>
</div>

@code {
    private IQueryable<Order> orders = OrderData.Create(10_000).AsQueryable();
}

With 10,000 orders, the DOM held 21 <tr> elements on load and 25 after I scrolled the box down, showing orders 7209 to 7233.

Important: pick paging or virtualization. I set both on a test page, and the grid showed 10 rows a page (10000 items Page 1 of 1000), so virtualization did nothing. Learn advises against the mix too.

Load Server-Side Data with QuickGrid ItemsProvider

When the data lives behind an API, use ItemsProvider instead of Items. QuickGrid calls it with the start index, row count and sort for each page:

@page "/orders-provider"
@rendermode InteractiveServer
@using Microsoft.AspNetCore.Components.QuickGrid
@using QuickGridDemo.Models
@using QuickGridDemo.Services
@inject ILogger<ProviderOrders> Logger

<PageTitle>Orders (ItemsProvider)</PageTitle>

<h1>Orders from an ItemsProvider</h1>

<QuickGrid ItemsProvider="provider" Pagination="pagination">
    <PropertyColumn Property="@(o => o.Id)" Title="Order #" Sortable="true" />
    <PropertyColumn Property="@(o => o.Customer)" Sortable="true" />
    <PropertyColumn Property="@(o => o.Total)" Format="C" Sortable="true" Align="Align.Right" Class="total" />
</QuickGrid>

<Paginator State="pagination" />

@code {
    private static readonly List<Order> all = OrderData.Create(200);
    private readonly PaginationState pagination = new() { ItemsPerPage = 10 };
    private GridItemsProvider<Order> provider = default!;

    protected override void OnInitialized()
    {
        // In a real app, this is where you'd call your web API with skip/take/sort parameters
        provider = request =>
        {
            Logger.LogInformation("StartIndex={Start}, Count={Count}, SortBy={Sort}", request.StartIndex,
                request.Count, string.Join(",", request.GetSortByProperties().Select(p => $"{p.PropertyName} {p.Direction}")));
            var page = request.ApplySorting(all.AsQueryable())
                .Skip(request.StartIndex)
                .Take(request.Count ?? 10)
                .ToList();
            return ValueTask.FromResult(GridItemsProviderResult.From(page, all.Count));
        };
    }
}

My logger printed these three requests: page 1, then next, then a click on Total:

StartIndex=0, Count=10, SortBy=
StartIndex=10, Count=10, SortBy=
StartIndex=10, Count=10, SortBy=Total Ascending

Notice the grid stayed on page 2 after sorting. In a real app, you’d send those values to your API with HttpClient in C# and return the rows plus the total count.

Use QuickGrid with EF Core and the EntityFrameworkAdapter

With EF Core, QuickGrid can page and sort in the database. Add the adapter and a provider (SQLite here, both 10.0.14):

dotnet add package Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter --version 10.0.14
dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 10.0.14

Here’s the project file after all three packages:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.QuickGrid" Version="10.0.14" />
    <PackageReference Include="Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter" Version="10.0.14" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="10.0.14" />
  </ItemGroup>

</Project>

The context is one DbSet in Data/SalesDbContext.cs:

using Microsoft.EntityFrameworkCore;
using QuickGridDemo.Models;

namespace QuickGridDemo.Data;

public class SalesDbContext(DbContextOptions<SalesDbContext> options) : DbContext(options)
{
    public DbSet<Order> Orders => Set<Order>();
}

AddQuickGridEntityFrameworkAdapter registers the async query executor. Here’s the final Program.cs, which also seeds sales.db with the same 200 orders:

using System.Globalization;
using QuickGridDemo.Components;
using Microsoft.EntityFrameworkCore;
using QuickGridDemo.Data;
using QuickGridDemo.Services;

// Show prices and dates the US way, whatever the server's regional settings are
CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddDbContextFactory<SalesDbContext>(options =>
    options.UseSqlite("Data Source=sales.db"));
builder.Services.AddQuickGridEntityFrameworkAdapter();

var app = builder.Build();

// Create sales.db with the same 200 orders the first time the app starts
using (var db = app.Services.GetRequiredService<IDbContextFactory<SalesDbContext>>().CreateDbContext())
{
    if (db.Database.EnsureCreated())
    {
        db.Orders.AddRange(OrderData.Create(200));
        db.SaveChanges();
    }
}

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

app.UseAntiforgery();

app.MapStaticAssets();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

The page uses a context factory, as Learn recommends, and disposes the context with the component. EF.Functions.Like keeps the search in SQL:

@page "/orders-db"
@rendermode InteractiveServer
@implements IAsyncDisposable
@using Microsoft.AspNetCore.Components.QuickGrid
@using Microsoft.EntityFrameworkCore
@using QuickGridDemo.Data
@using QuickGridDemo.Models
@inject IDbContextFactory<SalesDbContext> DbFactory

<PageTitle>Orders (EF Core)</PageTitle>

<h1>Orders from SQLite</h1>

<input id="search" class="form-control mb-2" style="max-width: 18rem;" placeholder="Search customer"
       @bind="search" @bind:event="oninput" />

<QuickGrid Items="Filtered" Pagination="pagination" Class="table table-sm">
    <PropertyColumn Property="@(o => o.Id)" Title="Order #" Sortable="true" IsDefaultSortColumn="true" />
    <PropertyColumn Property="@(o => o.Customer)" Sortable="true" />
    <PropertyColumn Property="@(o => o.State)" Sortable="true" />
    <PropertyColumn Property="@(o => o.Total)" Format="C" Sortable="true" Align="Align.Right" Class="total" />
</QuickGrid>

<Paginator State="pagination" />

@code {
    private SalesDbContext context = default!;
    private readonly PaginationState pagination = new() { ItemsPerPage = 10 };
    private string search = "";

    private IQueryable<Order> Filtered =>
        context.Orders.Where(o => EF.Functions.Like(o.Customer, $"%{search}%"));

    protected override void OnInitialized() => context = DbFactory.CreateDbContext();

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

After two clicks on Total and one on next, EF Core logged this query. Only 10 rows leave the database:

SELECT "o"."Id", "o"."Customer", "o"."OrderDate", "o"."State", "o"."Status", "o"."Total"
FROM "Orders" AS "o"
WHERE "o"."Customer" LIKE @Format
ORDER BY "o"."Total" COLLATE EF_DECIMAL DESC
LIMIT @p OFFSET @p

Two things surprised me. EF Core 10 sorted the decimal column in SQLite with COLLATE EF_DECIMAL, no value converter needed. And my first version, without IsDefaultSortColumn on Order #, made EF Core warn on every page:

The query uses a row limiting operator ('Skip'/'Take') without an 'OrderBy' operator. This may lead to unpredictable results. If the 'Distinct' operator is used after 'OrderBy', then make sure to use the 'OrderBy' operator after 'Distinct' as the ordering would otherwise get erased.

Without an ORDER BY, page 2 can repeat rows from page 1, so always give a database grid a default sort. For the full EF Core setup, see my ASP.NET Core Web API CRUD with EF Core guide.

Note: Learn also documents a QuickGrid scaffolder that builds CRUD pages from a model: dotnet aspnet-codegenerator blazor CRUD with -dbProvider, -dc, -m and -outDir. I didn’t run it here.

QuickGrid vs a Plain HTML Table: Which Should You Use?

I start every admin page with QuickGrid now. It’s free, it’s maintained by the ASP.NET Core team, and the whole grid fits in one Razor file.

Troubleshooting Blazor QuickGrid

Headers don’t sort and the Paginator does nothing. The page is static SSR. Add @rendermode InteractiveServer.

“The type or namespace name ‘QuickGrid’ could not be found”. The package is missing, or the page lacks @using Microsoft.AspNetCore.Components.QuickGrid. Put that line in _Imports.razor to cover every page.

Prices show the wrong currency symbol. Format="C" uses the server’s culture. Set en-US as in Step 1.

“A second operation was started on this context instance”. Learn lists this for concurrent EF Core queries. Create the context per component with IDbContextFactory, as DbOrders.razor does.

Note: before you put a grid like this online, lock the page down with [Authorize]. My JWT authentication guide covers the API side.

Where to Take It Next with Blazor QuickGrid

Add an Edit button in the Action column that opens a form, or export the filtered rows to CSV. If you’re moving an older grid app over, start with upgrading .NET 8 to .NET 10 to get RowClass.

A few more places to keep going:

• All Blazor tutorials
• ASP.NET Core tutorials for the back end
• C# 14 features you can use in components
• C# tutorials from the basics up

QuickGrid is itself a component that takes parameters like Items and Pagination. To build your own reusable pieces the same way, with required parameters, ChildContent and @key, see my tutorial on Blazor components and parameters in .NET 10.

Frequently Asked Questions

using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
Order? order = await http.GetFromJsonAsync<Order>("orders/1001");
Console.WriteLine($"{order!.Customer}, {order.City} {order.State}: ${order.Total}");

record Order(int Id, string Customer, string City, string State, decimal Total);
// Jenna Morales, Austin TX: $249.99

Every example below ran on .NET 10 against a small orders API I started on localhost, from POST and headers to timeouts, IHttpClientFactory and automatic retries.

The Sample Orders API Behind Every HttpClient Example

I didn’t want to call a public site you can’t control, so every program talks to a tiny local API. It holds three US orders and a few test endpoints. Here’s the record both sides share:

public record Order(int Id, string Customer, string City, string State, decimal Total);

And here’s the whole server, a minimal API in one file. The routes at the bottom (/slow, /flaky, /connection) exist only so the timeout, retry and reuse demos have something real to hit:

#!/usr/bin/env dotnet
#:sdk Microsoft.NET.Sdk.Web
#:property PublishAot=false
#:include Models.cs
using System.Collections.Concurrent;

var builder = WebApplication.CreateBuilder();
builder.WebHost.UseUrls("http://localhost:5736");
var app = builder.Build();

List<Order> orders =
[
    new(1001, "Jenna Morales", "Austin", "TX", 249.99m),
    new(1002, "Tyler Brooks", "Denver", "CO", 89.50m),
    new(1003, "Ava Kim", "Seattle", "WA", 412.00m)
];
var attempts = new ConcurrentDictionary<string, int>();

app.MapGet("/orders", () => orders);
app.MapGet("/orders/{id:int}", (int id) =>
    orders.Find(o => o.Id == id) is { } o ? Results.Ok(o) : Results.NotFound());
app.MapPost("/orders", (Order o) =>
{
    if (o.Total <= 0)
        return Results.Problem(title: "Invalid order", detail: "Total must be greater than $0.", statusCode: 400);
    orders.Add(o);
    return Results.Created($"/orders/{o.Id}", o);
});
app.MapPut("/orders/{id:int}", (int id, Order o) =>
{
    int i = orders.FindIndex(x => x.Id == id);
    if (i < 0) return Results.NotFound();
    orders[i] = o with { Id = id };
    return Results.NoContent();
});
app.MapDelete("/orders/{id:int}", (int id) =>
    orders.RemoveAll(o => o.Id == id) > 0 ? Results.NoContent() : Results.NotFound());
app.MapGet("/orders/search", (string? customer, string? state) => new { customer, state });
app.MapGet("/orders/export", () => Export(50_000));
app.MapGet("/headers", (HttpRequest r) => new
{
    userAgent = r.Headers.UserAgent.ToString(),
    accept = r.Headers.Accept.ToString(),
    requestId = r.Headers["X-Request-Id"].ToString()
});
app.MapGet("/secure/orders", (HttpRequest r) =>
    r.Headers.Authorization == "Bearer demo-token-2026" ? Results.Ok(orders) : Results.Unauthorized());
app.MapGet("/slow", async (CancellationToken ct) => { await Task.Delay(5000, ct); return "done"; });
app.MapGet("/flaky/{id}", (string id) =>
{
    int n = attempts.AddOrUpdate(id, 1, (_, count) => count + 1);
    return n <= 2 ? Results.StatusCode(503) : Results.Ok(new { attempt = n });
});
app.MapGet("/connection", (HttpContext ctx) => ctx.Connection.Id);

app.Run();

static async IAsyncEnumerable<Order> Export(int count)
{
    for (int i = 1; i <= count; i++)
    {
        yield return new(100_000 + i, $"Customer {i}", "Phoenix", "AZ", 10m + i % 90);
        if (i % 1_000 == 0) await Task.Yield();
    }
}

Start it with dotnet run ApiServer.cs and leave that terminal open. It printed Now listening on: http://localhost:5736 for me. These are .NET 10 file-based apps, so there’s no project file to create.

Want a real database behind the same routes? I built that in this ASP.NET Core Web API CRUD tutorial with EF Core. Every client below is a separate file in the same folder.

Method 1: HttpClient GET Request with GetStringAsync and GetAsync

Start here when you just need the raw response text, or when you want to look at the status code and headers before you read the body. Same orders API, two calls:

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };

string json = await http.GetStringAsync("orders/1002");
Console.WriteLine(json);

using HttpResponseMessage res = await http.GetAsync("orders/1003");
res.EnsureSuccessStatusCode();
Console.WriteLine($"{(int)res.StatusCode} {res.StatusCode}, {res.Content.Headers.ContentType}");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Output:

{"id":1002,"customer":"Tyler Brooks","city":"Denver","state":"CO","total":89.50}
200 OK, application/json; charset=utf-8
{"id":1003,"customer":"Ava Kim","city":"Seattle","state":"WA","total":412.00}

The first line is order 1002 as raw JSON. The second call returns 200 OK with application/json; charset=utf-8, then order 1003.

How does this code work?

GetStringAsync sends a GET and hands back the body as a string. It throws if the status isn’t 2xx, so you never see the response object.

GetAsync returns the full HttpResponseMessage. EnsureSuccessStatusCode() throws an HttpRequestException for anything outside 200-299, and Content.ReadAsStringAsync() reads the body.

Every method here is async, so the calls use await. If that’s new, read async and await in C# first; never call .Result on these tasks.

Important: the BaseAddress needs a trailing slash, and the relative paths don’t start with one. Otherwise the last segment of the base gets dropped.

Method 2: Read JSON with GetFromJsonAsync (Recommended)

Most APIs return JSON, and you want objects, not strings. This is the HttpClient method I reach for first. Here’s the same orders endpoint read straight into a list:

#!/usr/bin/env dotnet
#:property PublishAot=false
#:include Models.cs
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
List<Order> orders = (await http.GetFromJsonAsync<List<Order>>("orders"))!;

foreach (Order o in orders)
    Console.WriteLine($"{o.Id} {o.Customer,-14} {o.City}, {o.State}  ${o.Total}");
Console.WriteLine($"Total: ${orders.Sum(o => o.Total)}");

Output:

1001 Jenna Morales  Austin, TX  $249.99
1002 Tyler Brooks   Denver, CO  $89.50
1003 Ava Kim        Seattle, WA  $412.00
Total: $751.49

You get Jenna Morales in Austin, Tyler Brooks in Denver and Ava Kim in Seattle, with a total of $751.49.

How does this code work?

GetFromJsonAsync<T> lives in System.Net.Http.Json. It sends the GET, checks the status and deserializes the body with System.Text.Json using the Web defaults.

That’s why the camelCase JSON (customer, total) fills the PascalCase record without any attributes. The result is a List in C#, so the LINQ Sum works right away.

It returns T?, because the body could be the literal null. I use ! here since I control the API.

Method 3: HttpClient POST JSON with PostAsJsonAsync, then PUT and DELETE

Now let’s change data. Same sample orders, and this file adds order 1004, updates it, deletes it and then confirms it’s gone:

#!/usr/bin/env dotnet
#:property PublishAot=false
#:include Models.cs
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
var order = new Order(1004, "Marcus Reed", "Chicago", "IL", 129.95m);

using var post = await http.PostAsJsonAsync("orders", order);
Console.WriteLine($"POST   {(int)post.StatusCode} {post.Headers.Location}");
Console.WriteLine($"       {await post.Content.ReadFromJsonAsync<Order>()}");

var updated = order with { Total = 139.95m };
using var put = await http.PutAsJsonAsync("orders/1004", updated);
Console.WriteLine($"PUT    {(int)put.StatusCode} {put.StatusCode}");
using var del = await http.DeleteAsync("orders/1004");
Console.WriteLine($"DELETE {(int)del.StatusCode} {del.StatusCode}");
using var get = await http.GetAsync("orders/1004");
Console.WriteLine($"GET    {(int)get.StatusCode} {get.StatusCode}");

Output:

POST   201 /orders/1004
       Order { Id = 1004, Customer = Marcus Reed, City = Chicago, State = IL, Total = 129.95 }
PUT    204 NoContent
DELETE 204 NoContent
GET    404 NotFound

The POST answered 201 with Location: /orders/1004 and echoed Marcus Reed’s order. PUT and DELETE gave 204 NoContent, and the final GET gave 404.

How does this code work?

PostAsJsonAsync serializes the record to JSON, sets Content-Type: application/json and sends it. post.Headers.Location reads the URL the server put in the 201 response.

ReadFromJsonAsync<Order>() turns the response body back into a record. The order with { Total = 139.95m } copy is a record feature; see record vs class vs struct in C#.

DeleteAsync has no body parameter, and none of these methods throw on 404. They hand you the response, so check the status yourself.

PostAsync with StringContent (when you already have a JSON string)

If the JSON comes from a file or another system, there’s nothing to serialize. Wrap the string in StringContent and call PostAsync:

using System.Text;

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
string json = """{"id":1006,"customer":"Ava Kim","city":"Seattle","state":"WA","total":58.25}""";

using var content = new StringContent(json, Encoding.UTF8, "application/json");
using HttpResponseMessage res = await http.PostAsync("orders", content);
Console.WriteLine($"{(int)res.StatusCode} {res.StatusCode} {res.Headers.Location}");

await http.DeleteAsync("orders/1006");   // keep the sample API at three orders

Output:

201 Created /orders/1006

It returned 201 Created and /orders/1006; the last line deletes the order so the sample API stays at three orders.

The third StringContent argument sets the media type. Leave it out and the content type defaults to text/plain, and most APIs reject the request.

Method 4: How to Add Headers to HttpClient and Use SendAsync

Headers come in two flavors: ones every request needs, and ones that change per call. Same API, this time the /headers route, which echoes what it received:

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
http.DefaultRequestHeaders.UserAgent.ParseAdd("OrderSync/1.0");
http.DefaultRequestHeaders.Accept.ParseAdd("application/json");

using var request = new HttpRequestMessage(HttpMethod.Get, "headers");
request.Headers.Add("X-Request-Id", "req-20261108-001");

using HttpResponseMessage res = await http.SendAsync(request);
Console.WriteLine(await res.Content.ReadAsStringAsync());

Output:

{"userAgent":"OrderSync/1.0","accept":"application/json","requestId":"req-20261108-001"}

The server saw OrderSync/1.0, application/json and req-20261108-001.

How does this code work?

DefaultRequestHeaders applies to every request this client sends. Set them once, right after you create the client: Microsoft lists the send methods as thread safe, not the header collection.

For one call only, build an HttpRequestMessage, add headers to it and pass it to SendAsync. That’s also how you send an unusual verb like HttpMethod.Patch or HttpMethod.Head.

A request message can be sent once only, which is why both objects sit in using declarations. More on that in Dispose and Finalize in C#.

Method 5: Send an HttpClient Bearer Token with AuthenticationHeaderValue

Most real APIs want a token. The sample’s /secure/orders route returns the same orders only when the right bearer token arrives:

using System.Net.Http.Headers;

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
var res = await http.GetAsync("secure/orders");
Console.WriteLine($"No token:   {(int)res.StatusCode} {res.StatusCode}");

string token = "demo-token-2026";   // in a real app this comes from your identity provider
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

res = await http.GetAsync("secure/orders");
Console.WriteLine($"With token: {(int)res.StatusCode} {res.StatusCode}");

Output:

No token:   401 Unauthorized
With token: 200 OK

Without the header the API answered 401 Unauthorized; with it, 200 OK.

How does this code work?

new AuthenticationHeaderValue("Bearer", token) writes Authorization: Bearer demo-token-2026. Setting it on DefaultRequestHeaders adds it to every later call from this client.

If different users share one client, put the header on each HttpRequestMessage instead. For the server side, see JWT authentication in ASP.NET Core.

Note: never hard-code real tokens. Read them from your identity provider, user secrets or a key vault.

Method 6: Build HttpClient Query Strings with Uri.EscapeDataString

Query strings look like plain string building, until a value contains &. Here’s a search for a business customer on the same API, done the naive way first:

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
string customer = "Brooks & Lee LLC";

Console.WriteLine(await http.GetStringAsync($"orders/search?customer={customer}&state=CO"));

string url = $"orders/search?customer={Uri.EscapeDataString(customer)}&state=CO";
Console.WriteLine(url);
Console.WriteLine(await http.GetStringAsync(url));

Output:

{"customer":"Brooks ","state":"CO"}
orders/search?customer=Brooks%20%26%20Lee%20LLC&state=CO
{"customer":"Brooks & Lee LLC","state":"CO"}

The naive call sent customer as "Brooks ". The encoded URL sent Brooks%20%26%20Lee%20LLC, and the server got the full name back.

How does this code work?

An unescaped & starts a new parameter, so the server split the name in two. Uri.EscapeDataString turns spaces into %20 and & into %26.

Escape every value that comes from a user or a database. In ASP.NET Core, QueryHelpers.AddQueryString builds and encodes the whole string for you.

Method 7: Handle HttpClient Errors with HttpRequestException and ProblemDetails

Things go wrong in three different ways: a 4xx/5xx status, a validation error with details, or no server at all. This file hits all three against the sample API:

#!/usr/bin/env dotnet
#:property PublishAot=false
#:include Models.cs
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };
try { await http.GetFromJsonAsync<Order>("orders/9999"); }
catch (HttpRequestException ex) { Console.WriteLine($"{(int?)ex.StatusCode}: {ex.Message}"); }

var res = await http.PostAsJsonAsync("orders", new Order(1005, "Ava Kim", "Seattle", "WA", 0m));
if (!res.IsSuccessStatusCode)
{
    Problem p = (await res.Content.ReadFromJsonAsync<Problem>())!;
    Console.WriteLine($"{p.Status} {p.Title}: {p.Detail}");
}

try { await http.GetStringAsync("http://localhost:5799/orders"); }
catch (HttpRequestException ex)
{
    Console.WriteLine($"{ex.HttpRequestError}, StatusCode is null: {ex.StatusCode is null}");
}

record Problem(string Title, int Status, string Detail);

Output:

404: Response status code does not indicate success: 404 (Not Found).
400 Invalid order: Total must be greater than $0.
ConnectionError, StatusCode is null: True

Order 9999 gave a 404 exception, the $0 order came back as 400 Invalid order with the server’s message, and port 5799 failed with ConnectionError.

How does this code work?

GetFromJsonAsync throws HttpRequestException on a non-success status, and ex.StatusCode tells you which one. Catch it in a try-catch block where the call happens.

PostAsJsonAsync doesn’t throw on 400, so I check IsSuccessStatusCode and read the problem details JSON the API sent. ASP.NET Core’s Results.Problem writes title, status and detail.

When there’s no response at all, StatusCode is null, so check it for null. HttpRequestError (.NET 8+) tells you why: ConnectionError, NameResolutionError and so on.

Method 8: HttpClient Timeout and CancellationToken

The /slow route takes 5 seconds to answer. Here’s one client with a 2-second Timeout, and the same call canceled by a token after 1 second:

Console.WriteLine($"Default timeout: {new HttpClient().Timeout}");

using var http = new HttpClient
{
    BaseAddress = new("http://localhost:5736/"),
    Timeout = TimeSpan.FromSeconds(2)
};
try { await http.GetStringAsync("slow"); }
catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
{ Console.WriteLine($"Timeout: {ex.Message}"); }

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(1));
try { await http.GetStringAsync("slow", cts.Token); }
catch (TaskCanceledException ex)
{ Console.WriteLine($"Canceled: {ex.Message} TimeoutException? {ex.InnerException is TimeoutException}"); }

Output:

Default timeout: 00:01:40
Timeout: The request was canceled due to the configured HttpClient.Timeout of 2 seconds elapsing.
Canceled: The operation was canceled. TimeoutException? False

The default prints 00:01:40. The timeout message names HttpClient.Timeout of 2 seconds, and the token cancel says The operation was canceled. with no TimeoutException.

How does this code work?

The default HttpClient.Timeout is 100 seconds. It covers the whole request on that client, and you can only set it before the first request.

Both cases throw TaskCanceledException. On .NET 5 and later, a timeout carries a TimeoutException as InnerException, and the when filter uses that to tell them apart.

Pro Tip: keep Timeout as a safety net and pass a CancellationToken for per-call limits or a user’s Cancel button. Learn notes that only the shorter of the two applies.

Why Shouldn’t You Create a New HttpClient for Every Request?

This is the mistake I see most in code reviews. HttpClient implements IDisposable, so people wrap each call in using. The sample API’s /connection route returns the TCP connection ID, so we can count connections:

const string Url = "http://localhost:5736/connection";

var perCall = new HashSet<string>();
for (int i = 0; i < 5; i++)
{
    using var client = new HttpClient();          // the mistake
    perCall.Add(await client.GetStringAsync(Url));
}
Console.WriteLine($"New HttpClient per call: {perCall.Count} TCP connections");

var shared = new HttpClient(new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2)
});
var reused = new HashSet<string>();
for (int i = 0; i < 5; i++) reused.Add(await shared.GetStringAsync(Url));
Console.WriteLine($"One shared HttpClient:   {reused.Count} TCP connection");

Output:

New HttpClient per call: 5 TCP connections
One shared HttpClient:   1 TCP connection

Five calls through five new clients opened 5 TCP connections. The shared client sent all five over 1 connection.

How does this code work?

Each HttpClient owns its own connection pool, so disposing it closes the socket. A closed socket sits in TIME_WAIT for a while, and a busy app running that for loop at scale runs out of ports.

Microsoft Learn’s guidance for .NET Core and .NET 5+ is either a long-lived static or singleton client with PooledConnectionLifetime set, or short-lived clients from IHttpClientFactory.

PooledConnectionLifetime recycles connections every 2 minutes here, so DNS changes get picked up. Without it, a shared client keeps the old IP address forever.

Method 9: IHttpClientFactory with Named and Typed Clients

In ASP.NET Core or a worker service, let the container hand out clients. Same orders API, now through a generic host with a named client and a typed client:

#!/usr/bin/env dotnet
#:property PublishAot=false
#:package Microsoft.Extensions.Hosting@10.0.14
#:package Microsoft.Extensions.Http@10.0.14
#:include Models.cs
using System.Net.Http.Json;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder();
builder.Logging.ClearProviders();
builder.Services.AddHttpClient("orders", c => c.BaseAddress = new("http://localhost:5736/"));
builder.Services.AddHttpClient<OrdersClient>(c => c.BaseAddress = new("http://localhost:5736/"));
using IHost host = builder.Build();

var factory = host.Services.GetRequiredService<IHttpClientFactory>();
HttpClient named = factory.CreateClient("orders");
var all = await named.GetFromJsonAsync<List<Order>>("orders");
Console.WriteLine($"Named client: {all!.Count} orders");

var typed = host.Services.GetRequiredService<OrdersClient>();
Order o = await typed.GetAsync(1002);
Console.WriteLine($"Typed client: {o.Customer}, {o.City} {o.State}");

class OrdersClient(HttpClient http)
{
    public async Task<Order> GetAsync(int id) =>
        (await http.GetFromJsonAsync<Order>($"orders/{id}"))!;
}

Output:

Named client: 3 orders
Typed client: Tyler Brooks, Denver CO

The named client read 3 orders, and the typed client returned Tyler Brooks in Denver, CO. Packages: Microsoft.Extensions.Hosting 10.0.14 and Microsoft.Extensions.Http 10.0.14.

How does this code work?

AddHttpClient("orders", ...) registers a named client; factory.CreateClient("orders") builds a new HttpClient with that base address. The factory pools the handlers underneath, so creating clients is cheap.

AddHttpClient<OrdersClient> registers a typed client. The primary constructor receives a configured HttpClient, and the class wraps the API in real methods like GetAsync(1002).

Typed clients are registered as transient, and handlers are recycled every 2 minutes by default. Don’t capture a typed client in a singleton. In tests, put an interface in front of OrdersClient.

In ASP.NET Core, the same builder.Services.AddHttpClient lines go in Program.cs, and you inject OrdersClient into an endpoint or controller.

Method 10: HttpClient Retries with AddStandardResilienceHandler

Networks fail for a second and then recover. The /flaky/{id} route on the same API returns 503 for the first two calls with a given ID and succeeds on the third:

#!/usr/bin/env dotnet
#:package Microsoft.Extensions.Hosting@10.0.14
#:package Microsoft.Extensions.Http.Resilience@10.11.0
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

const string Api = "http://localhost:5736/";
var builder = Host.CreateApplicationBuilder();
builder.Logging.ClearProviders();
builder.Services.AddHttpClient("orders", c => c.BaseAddress = new(Api))
    .AddStandardResilienceHandler();
using IHost host = builder.Build();

using var plain = new HttpClient { BaseAddress = new(Api) };
var first = await plain.GetAsync($"flaky/{Guid.NewGuid():N}");
Console.WriteLine($"Plain HttpClient: {(int)first.StatusCode} {first.StatusCode}");

var factory = host.Services.GetRequiredService<IHttpClientFactory>();
HttpClient http = factory.CreateClient("orders");
var res = await http.GetAsync($"flaky/{Guid.NewGuid():N}");
Console.WriteLine($"With resilience:  {(int)res.StatusCode} {await res.Content.ReadAsStringAsync()}");

Output:

Plain HttpClient: 503 ServiceUnavailable
With resilience:  200 {"attempt":3}

The plain client got 503 ServiceUnavailable. The resilient client returned 200 with {"attempt":3}: two failures, then success, with no retry code of mine.

How does this code work?

AddStandardResilienceHandler() comes from Microsoft.Extensions.Http.Resilience (10.11.0 here). It stacks a rate limiter, a 30-second total timeout, retries, a circuit breaker and a 10-second per-attempt timeout.

The retry part makes up to 3 retries with exponential backoff and jitter, starting at 2 seconds. It retries 5xx, 408 and 429 responses plus HttpRequestException. Each test uses a new GUID so its counter starts fresh.

Important: it retries every HTTP method by default, including POST. Call options.Retry.DisableForUnsafeHttpMethods() if a repeated POST could create duplicate orders.

Method 11: Stream a Large Response with ResponseHeadersRead

By default, GetAsync buffers the whole body in memory before it returns. For a big export that’s wasteful. The sample API’s /orders/export route streams 50,000 orders:

#!/usr/bin/env dotnet
#:property PublishAot=false
#:include Models.cs
using System.Globalization;
using System.Text.Json;

CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US");
using var http = new HttpClient { BaseAddress = new("http://localhost:5736/") };

using HttpResponseMessage res = await http.GetAsync("orders/export", HttpCompletionOption.ResponseHeadersRead);
res.EnsureSuccessStatusCode();
await using Stream body = await res.Content.ReadAsStreamAsync();

int count = 0; decimal total = 0;
await foreach (Order? o in JsonSerializer.DeserializeAsyncEnumerable<Order>(body, JsonSerializerOptions.Web))
{
    count++; total += o!.Total;
}
Console.WriteLine($"Streamed {count:N0} orders worth {total:C}");

Output:

Streamed 50,000 orders worth $2,724,050.00

It streamed 50,000 orders worth $2,724,050.00 without ever holding the full JSON in memory.

How does this code work?

HttpCompletionOption.ResponseHeadersRead makes GetAsync return as soon as the headers arrive. ReadAsStreamAsync then gives you the body as it downloads.

DeserializeAsyncEnumerable yields one order at a time to the await foreach loop. GetFromJsonAsAsyncEnumerable does the same in one call. The culture line keeps the number and currency formatting in US style.

Dispose the response when you’re done. With ResponseHeadersRead, the connection stays busy until you read or dispose the body.

HttpClient vs IHttpClientFactory vs WebClient vs RestSharp

These come up in every code review and in .NET interviews. Here’s how I’d pick in 2026:

HttpClient vs IHttpClientFactory isn’t really a contest: the factory creates HttpClient objects. If you’re prepping for interviews, these .NET Core interview questions cover the follow-ups.

Which HttpClient Method Should You Use?

Things to Keep in Mind

• Reuse the client. One shared instance with PooledConnectionLifetime, or IHttpClientFactory; never new HttpClient() per call.
• Only some methods throw on errors. GetStringAsync and GetFromJsonAsync throw; GetAsync, PostAsJsonAsync and DeleteAsync return the response.
• Timeouts throw TaskCanceledException. Check InnerException is TimeoutException to tell a timeout from a cancel.
• Escape query values. Uri.EscapeDataString for anything a user typed.
• Don’t retry POST blindly. Turn off retries for unsafe methods unless the API is idempotent.

Here’s what I’d read next:

• C# 14 features worth using in your API clients
• Upgrade a .NET 8 app to .NET 10
• Check which .NET version your app runs on
• Browse every C# tutorial on aspdotnethelp.com

Frequently Asked Questions

ArgumentOutOfRangeException: IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'HS256', the key size must be greater than: '256' bits, key has '128' bits. (Parameter 'keyBytes')

HS256 needs a signing key of at least 256 bits, and that string is only 128. The fix is a long random key kept in user secrets, plus AddJwtBearer checking the issuer, audience, signature and lifetime of every token.

Here’s what we’re building, a .NET 10 payroll API answering a real HttpClient test run:

How Does JWT Bearer Authentication Work in ASP.NET Core?

A JSON Web Token is three Base64Url parts joined by dots: a header, a payload of claims and a signature. Your API signs it at login, and the client sends it back on every call in an Authorization: Bearer header.

Failing step 4 gives a 401, and passing it but failing step 5 gives a 403. That split is what the test run above shows. If minimal APIs are new to you, the ASP.NET Core Web API CRUD tutorial builds one from scratch.

Before You Start the JWT Build

You need the .NET 10 SDK (I used 10.0.402) and any editor; I used VS Code. Not sure which SDK you have? Check your .NET version first. Here’s the NuGet package and the library it brings in:

The sample API has two demo users and four endpoints. Tyler works in Operations, and Jenna runs payroll in Finance:

Step 1: Create the Minimal API and Add the JwtBearer Package

Start from the empty web template and add the JWT bearer handler at the exact version I tested:

dotnet new web -n PayrollApi -o PayrollApi
cd PayrollApi
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 10.0.14

I trimmed Properties/launchSettings.json to one http profile on port 5735. It also sets the Development environment, which matters in Step 2:

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5735",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

I deleted appsettings.Development.json since nothing here needs it. Here’s the project file after Step 2 adds the user secrets ID:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UserSecretsId>a911f57d-d8b7-444f-b815-6f906b67e6e9</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.14" />
  </ItemGroup>

</Project>

Checkpoint: dotnet build succeeds and the csproj references JwtBearer 10.0.14.

Step 2: Store the JWT Signing Key with dotnet user-secrets

The issuer, audience and token lifetime aren’t secret, so they go in appsettings.json. The signing key is, so it doesn’t:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Jwt": {
    "Issuer": "payroll-api-demo",
    "Audience": "payroll-web",
    "AccessTokenMinutes": 15
  }
}

Anyone holding the key can mint a valid token for any user. Generate 48 random bytes and save them as a user secret without ever printing them (PowerShell 7):

dotnet user-secrets init
$key = [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48))
dotnet user-secrets set "Jwt:SigningKey" $key

Successfully saved Jwt:SigningKey to the secret store.

User secrets live in your Windows profile, outside the repo, and WebApplication.CreateBuilder loads them only in Development. In production, set an environment variable named Jwt__SigningKey (double underscore) or read it from Azure Key Vault.

Why 48 bytes? The 64-character Base64 text becomes the key bytes through Encoding.UTF8.GetBytes, so that’s 512 bits. Here’s the short key from the intro, run on its own so you can see the real exception:

#:package Microsoft.IdentityModel.JsonWebTokens@8.19.2
using System.Text;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("my-secret-key-16"));
Console.WriteLine($"Key size: {key.KeySize} bits");
try
{
    new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
    {
        Issuer = "payroll-api-demo",
        SigningCredentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256)
    });
}
catch (Exception ex) { Console.WriteLine($"{ex.GetType().Name}: {ex.Message}"); }

Output:

Key size: 128 bits
ArgumentOutOfRangeException: IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'HS256', the key size must be greater than: '256' bits, key has '128' bits. (Parameter 'keyBytes')

It’s a file-based app, so the #:package line pulls the same JsonWebTokens version the API uses. The API’s Program.cs checks KeySize at startup, so a weak key fails before the first request.

Checkpoint: dotnet user-secrets list shows a Jwt:SigningKey entry, and the value never lands in a file inside the project.

Step 3: Configure AddJwtBearer with TokenValidationParameters

This block tells the JWT bearer handler what a good token looks like. Every check is on, and the values come from configuration:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.MapInboundClaims = false;          // keep "name" and "role" as they are in the token
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = jwt["Issuer"],
            ValidateAudience = true,
            ValidAudience = jwt["Audience"],
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = signingKey,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.Zero,             // the default is 5 minutes
            NameClaimType = "name",
            RoleClaimType = "role"
        };
    });

MapInboundClaims = false keeps short claim names like role instead of the long WS-Federation URIs, so NameClaimType and RoleClaimType point at the names I issue.

Since ASP.NET Core 8, the handler validates with the newer JsonWebTokenHandler by default (Microsoft quotes about 30% faster). Set UseSecurityTokenValidators = true only if old code casts to JwtSecurityToken.

The explicit app.UseAuthentication() and app.UseAuthorization() calls are optional on .NET 10, because WebApplication adds both when the services exist. I keep them so the order is visible, and the Troubleshooting section shows what happens when it’s wrong.

Checkpoint: the API starts and logs the Development environment on port 5735:

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5735
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\DotNetDemo\JwtAuthDemo\PayrollApi

Step 4: Generate the JWT Token in a /login Endpoint

This is the generate-a-JWT-token part. I use JsonWebTokenHandler.CreateToken with a SecurityTokenDescriptor. The older JwtSecurityTokenHandler from System.IdentityModel.Tokens.Jwt still works, but it’s the previous generation:

app.MapPost("/login", (LoginRequest login) =>
{
    var user = DemoUsers.Find(login.Username, login.Password);
    if (user is null) return Results.Unauthorized();

    var expires = DateTime.UtcNow.AddMinutes(jwt.GetValue<double>("AccessTokenMinutes"));
    var token = new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
    {
        Issuer = jwt["Issuer"],
        Audience = jwt["Audience"],
        Expires = expires,
        Subject = new ClaimsIdentity(
        [
            new Claim(JwtRegisteredClaimNames.Sub, user.Username),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
            new Claim("name", user.FullName),
            new Claim("department", user.Department),
            .. user.Roles.Select(role => new Claim("role", role))
        ]),
        SigningCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256)
    });
    return Results.Ok(new TokenResponse(token, expires));
});

Each token gets a GUID as its jti (token ID), one role claim per role, and a 15-minute expiry from configuration. The request and response types are C# records.

Calling it with Tyler’s demo login returns the token (I cut it to 24 characters here) and its expiry:

curl.exe -s -X POST http://localhost:5735/login -H "Content-Type: application/json" -d "{\"username\":\"tbrooks\",\"password\":\"demo-tyler-2026\"}"

{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5...","expiresAt":"2026-11-01T13:53:20.2627547Z"}

Checkpoint: a wrong password returns 401 and no token, and a correct one returns a token starting with eyJ.

Step 5: Protect Endpoints with RequireAuthorization, JWT Roles and Claims

Authentication only tells you who’s calling. Nothing is locked until an endpoint asks for it. Two named policies cover the role rule and the claim rule:

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("PayrollOnly", policy => policy.RequireRole("Payroll"))
    .AddPolicy("FinanceOnly", policy => policy.RequireClaim("department", "Finance"));

app.MapGet("/me", (ClaimsPrincipal user) => new
{
    Name = user.Identity?.Name,
    Department = user.FindFirstValue("department"),
    Roles = user.FindAll("role").Select(r => r.Value)
}).RequireAuthorization();

app.MapGet("/payroll", () => DemoUsers.Payroll).RequireAuthorization("PayrollOnly");

app.MapGet("/budget", () => new { Quarter = "Q4 2026", Budget = 184_500m })
    .RequireAuthorization("FinanceOnly");

RequireAuthorization() with no name means any valid token. In controllers, the same rule is [Authorize] or [Authorize(Policy = "PayrollOnly")]. Here’s the whole Program.cs at this point:

using System.Security.Claims;
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

var jwt = builder.Configuration.GetSection("Jwt");
var keyText = jwt["SigningKey"]
    ?? throw new InvalidOperationException("Jwt:SigningKey is missing. Set it with dotnet user-secrets.");
var signingKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(keyText));
if (signingKey.KeySize < 256)
    throw new InvalidOperationException($"Jwt:SigningKey has {signingKey.KeySize} bits; HS256 needs 256 or more.");

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.MapInboundClaims = false;          // keep "name" and "role" as they are in the token
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = jwt["Issuer"],
            ValidateAudience = true,
            ValidAudience = jwt["Audience"],
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = signingKey,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.Zero,             // the default is 5 minutes
            NameClaimType = "name",
            RoleClaimType = "role"
        };
    });

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("PayrollOnly", policy => policy.RequireRole("Payroll"))
    .AddPolicy("FinanceOnly", policy => policy.RequireClaim("department", "Finance"));

var app = builder.Build();

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

app.MapGet("/health", () => "OK");

app.MapPost("/login", (LoginRequest login) =>
{
    var user = DemoUsers.Find(login.Username, login.Password);
    if (user is null) return Results.Unauthorized();

    var expires = DateTime.UtcNow.AddMinutes(jwt.GetValue<double>("AccessTokenMinutes"));
    var token = new JsonWebTokenHandler().CreateToken(new SecurityTokenDescriptor
    {
        Issuer = jwt["Issuer"],
        Audience = jwt["Audience"],
        Expires = expires,
        Subject = new ClaimsIdentity(
        [
            new Claim(JwtRegisteredClaimNames.Sub, user.Username),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
            new Claim("name", user.FullName),
            new Claim("department", user.Department),
            .. user.Roles.Select(role => new Claim("role", role))
        ]),
        SigningCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256)
    });
    return Results.Ok(new TokenResponse(token, expires));
});

app.MapGet("/me", (ClaimsPrincipal user) => new
{
    Name = user.Identity?.Name,
    Department = user.FindFirstValue("department"),
    Roles = user.FindAll("role").Select(r => r.Value)
}).RequireAuthorization();

app.MapGet("/payroll", () => DemoUsers.Payroll).RequireAuthorization("PayrollOnly");

app.MapGet("/budget", () => new { Quarter = "Q4 2026", Budget = 184_500m })
    .RequireAuthorization("FinanceOnly");

app.Run();

record LoginRequest(string Username, string Password);
record TokenResponse(string AccessToken, DateTime ExpiresAt);
record DemoUser(string Username, string Password, string FullName, string Department, string[] Roles);
record PayrollRow(string Employee, string City, string State, decimal AnnualSalary);

static class DemoUsers
{
    // Demo only. A real app checks hashed passwords (ASP.NET Core Identity) or uses an identity provider.
    static readonly DemoUser[] Users =
    [
        new("tbrooks", "demo-tyler-2026", "Tyler Brooks", "Operations", ["Employee"]),
        new("jmorales", "demo-jenna-2026", "Jenna Morales", "Finance", ["Employee", "Payroll"]),
    ];

    public static DemoUser? Find(string username, string password) =>
        Users.FirstOrDefault(u => u.Username == username && u.Password == password);

    public static readonly PayrollRow[] Payroll =
    [
        new("Tyler Brooks", "Columbus", "OH", 58_400m),
        new("Jenna Morales", "Austin", "TX", 91_250m),
        new("Rachel Kim", "Seattle", "WA", 104_800m),
    ];
}

Calling /me with no token proves the lock and shows the challenge header the HTTP spec requires:

HTTP/1.1 401 Unauthorized
Content-Length: 0
Server: Kestrel
WWW-Authenticate: Bearer

Checkpoint: no token gives 401 with WWW-Authenticate: Bearer, and Jenna’s token on /me returns {"name":"Jenna Morales","department":"Finance","roles":["Employee","Payroll"]}.

Step 6: Decode the JWT and Read Its Claims

A JWT is signed, not encrypted. Anyone with the token can read the payload, which this little client proves. It uses System.Text.Json and the Base64Url class from .NET 9:

#:property PublishAot=false
using System.Buffers.Text;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("http://localhost:5735") };
var login = await http.PostAsJsonAsync("/login", new { username = "jmorales", password = "demo-jenna-2026" });
string token = (await login.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("accessToken").GetString()!;

string[] parts = token.Split('.');
Console.WriteLine($"{parts.Length} parts, {token.Length} characters: {token[..20]}...");
var pretty = new JsonSerializerOptions { WriteIndented = true };
foreach (var (label, part) in new[] { ("Header", parts[0]), ("Payload", parts[1]) })
{
    using var doc = JsonDocument.Parse(Encoding.UTF8.GetString(Base64Url.DecodeFromChars(part)));
    Console.WriteLine($"{label}: {JsonSerializer.Serialize(doc.RootElement, pretty)}");
}

Output:

3 parts, 395 characters: eyJhbGciOiJIUzI1NiIs...
Header: {
  "alg": "HS256",
  "typ": "JWT"
}
Payload: {
  "aud": "payroll-web",
  "iss": "payroll-api-demo",
  "exp": 1793541200,
  "sub": "jmorales",
  "jti": "dc270880-8f35-4dc4-a159-c811c1751823",
  "name": "Jenna Morales",
  "department": "Finance",
  "role": [
    "Employee",
    "Payroll"
  ],
  "iat": 1793540300,
  "nbf": 1793540300
}

The claims match the descriptor. exp, iat and nbf are Unix seconds, and role became a JSON array because Jenna has two roles. Never put a password, SSN or anything private in a claim.

Checkpoint: the payload shows "iss": "payroll-api-demo" and "aud": "payroll-web", the same values the API validates.

Test the JWT Bearer Authentication with HttpClient

This client logs in both users and calls every endpoint. It’s plain async/await in C# with one HttpClient:

#:property PublishAot=false
using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("http://localhost:5735") };

async Task<string> Login(string user, string pass) =>
    (await (await http.PostAsJsonAsync("/login", new { username = user, password = pass }))
        .Content.ReadFromJsonAsync<Token>())!.AccessToken;

async Task Call(string path, string? token, string who)
{
    var req = new HttpRequestMessage(HttpMethod.Get, path);
    if (token is not null) req.Headers.Authorization = new("Bearer", token);
    var res = await http.SendAsync(req);
    string hint = string.Join(" ", res.Headers.WwwAuthenticate.Select(h => h.Scheme));
    Console.WriteLine($"{path,-9}{who,-20}{(int)res.StatusCode} {res.StatusCode} {hint}");
}

string tyler = await Login("tbrooks", "demo-tyler-2026");
string jenna = await Login("jmorales", "demo-jenna-2026");
await Call("/health", null, "no token");
await Call("/me", null, "no token");
await Call("/me", tyler, "Tyler (Employee)");
await Call("/payroll", tyler, "Tyler (Employee)");
await Call("/budget", tyler, "Tyler (Operations)");
await Call("/payroll", jenna, "Jenna (Payroll)");
await Call("/budget", jenna, "Jenna (Finance)");
await Call("/me", tyler[..^4] + "AAAA", "tampered token");

record Token(string AccessToken, DateTime ExpiresAt);

Output:

/health  no token            200 OK 
/me      no token            401 Unauthorized Bearer
/me      Tyler (Employee)    200 OK 
/payroll Tyler (Employee)    403 Forbidden 
/budget  Tyler (Operations)  403 Forbidden 
/payroll Jenna (Payroll)     200 OK 
/budget  Jenna (Finance)     200 OK 
/me      tampered token      401 Unauthorized Bearer

Note: file-based apps publish as Native AOT by default, which turns off reflection-based JSON. My first run of PostAsJsonAsync died with “Reflection-based serialization has been disabled”, so the clients start with #:property PublishAot=false.

What each JWT test result means

The tampered call changed the last four characters of the signature. The full response header says why:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The signature key was not found"

Test an expired JWT token (lifetime and ClockSkew)

For this run I started the API with Jwt__AccessTokenMinutes=0.1, a six-second token, and waited eight seconds between calls:

#:property PublishAot=false
using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("http://localhost:5735") };
var login = await http.PostAsJsonAsync("/login", new { username = "tbrooks", password = "demo-tyler-2026" });
var token = (await login.Content.ReadFromJsonAsync<Token>())!;
http.DefaultRequestHeaders.Authorization = new("Bearer", token.AccessToken);
Console.WriteLine($"Token expires at {token.ExpiresAt:HH:mm:ss} UTC");

for (int i = 0; i < 2; i++)
{
    var res = await http.GetAsync("/me");
    Console.WriteLine($"{DateTime.UtcNow:HH:mm:ss}  GET /me -> {(int)res.StatusCode} {res.StatusCode}");
    foreach (var h in res.Headers.WwwAuthenticate) Console.WriteLine($"  WWW-Authenticate: {h}");
    if (i == 0) await Task.Delay(TimeSpan.FromSeconds(8));
}

record Token(string AccessToken, DateTime ExpiresAt);

Output:

Token expires at 13:39:33 UTC
13:39:27  GET /me -> 200 OK
13:39:35  GET /me -> 401 Unauthorized
  WWW-Authenticate: Bearer error="invalid_token", error_description="The token expired at '11/01/2026 13:39:33'"

It failed right on time because ClockSkew is zero. With the default five minutes, that token would have kept working for five more minutes.

Generate a Dev JWT Token with dotnet user-jwts

Don’t want a /login endpoint while you build? The dotnet user-jwts tool mints local tokens and keeps its signing key in user secrets. It works when AddJwtBearer() reads its options from configuration, so I used a second small project:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication("Bearer").AddJwtBearer();   // options come from appsettings
builder.Services.AddAuthorization();

var app = builder.Build();

app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}, you're in.")
    .RequireAuthorization();
app.MapGet("/payroll", () => "Payroll data for Q4 2026")
    .RequireAuthorization(p => p.RequireRole("Payroll"));

app.Run();

It has the same launchSettings.json as PayrollApi. Create a token for Jenna with the Payroll role:

dotnet user-jwts create --name "Jenna Morales" --role Payroll

New JWT saved with ID 'ca875434'.
Name: Jenna Morales
Roles: [Payroll]

Token: eyJhbGciOiJIUzI1NiIsInR5...

The tool also wrote the matching issuer and audience into appsettings.Development.json, and it added a UserSecretsId to the csproj:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Authentication": {
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "http://localhost:5735"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      }
    }
  }
}

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UserSecretsId>1acd2c24-eb31-4a71-a13c-3a7ab23a1a79</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.14" />
  </ItemGroup>

</Project>

dotnet user-jwts print with the ID shows everything in the token, including the claims and the expiry:

dotnet user-jwts print ca875434 --show-all

Found JWT with ID 'ca875434'.
ID: ca875434
Name: Jenna Morales
Scheme: Bearer
Audience(s): http://localhost:5735
Not Before: 2026-11-01T13:41:42.0000000+00:00
Expires On: 2027-02-01T13:41:42.0000000+00:00
Issued On: 2026-11-01T13:41:43.0000000+00:00
Scopes: none
Roles: [Payroll]
Custom Claims: [none]
Token Header: {"alg":"HS256","typ":"JWT"}
Token Payload: {"unique_name":"Jenna Morales","sub":"Jenna Morales","jti":"ca875434","role":"Payroll","aud":"http://localhost:5735","nbf":1793540502,"exp":1801489302,"iat":1793540503,"iss":"dotnet-user-jwts"}
Compact Token: eyJhbGciOiJIUzI1NiIsInR5...

With that token, /secret answered Hello Jenna Morales, you're in. and /payroll returned 200. Without it, /secret returned 401. My token expires three months out, as the tool’s help says.

JWT Refresh Tokens: What They Do (Not Built Here)

A short access token is safer, but nobody wants to sign in every 15 minutes. A refresh token is a long random value, stored on the server, that the client trades for a new access token.

The server rotates it on every use, revokes it on sign-out, and never puts it in browser storage. That’s real work, which is why I’d lean on ASP.NET Core Identity or an identity provider before writing my own.

ASP.NET Core Identity vs JWT, and Cookie vs JWT: Which One Do You Need?

These aren’t really rivals. Identity stores users and passwords, while cookies and JWTs are two ways to carry the signed-in user on each request:

Identity can issue bearer tokens too, through MapIdentityApi. If a code-based sign-in fits your users better than passwords, my OTP sign-in example in ASP.NET Core covers that half.

Make the ASP.NET Core JWT Setup Production-Ready

• HTTPS only. A bearer token works like a password until it expires, so never send it over plain HTTP outside localhost.
• Short lifetimes. 5 to 15 minutes for access tokens, with ClockSkew of 30 seconds or less.
• Keep the key out of the repo. User secrets in development, Key Vault or an environment variable in production, and rotate it.
• Store tokens safely. Don’t keep them in browser localStorage; use a backend with an HttpOnly cookie for browser apps.
• Use an identity provider for real users. Microsoft recommends asymmetric keys and OAuth or OpenID Connect flows over issuing tokens from a username and password.

Want a token box in your API docs? My OpenAPI and Scalar guide for ASP.NET Core adds the Bearer security scheme so you can paste a JWT and try the locked endpoints.

Troubleshooting ASP.NET Core JWT Authentication Errors

IDX10720: the key size must be greater than ‘256’ bits. Your HS256 key is shorter than 32 bytes. Generate a new one as in Step 2.

A valid token still gets 401. I swapped the two middleware lines so UseAuthorization ran first, and Tyler’s good token on /me returned 401. Authentication must run before authorization.

Everyone gets in. The endpoint has no RequireAuthorization, exactly like /health, which returned 200 with no token. To lock every endpoint by default, set a fallback policy with SetFallbackPolicy.

Roles never match, so every call is 403. With MapInboundClaims = false you must set RoleClaimType = "role". Leave mapping on and the handler renames role to the long ClaimTypes.Role URI instead.

Expired tokens still work for a few minutes. That’s the 5-minute default ClockSkew. Lower it, as in Step 3.

dotnet user-jwts says it could not find appsettings.Development.json. I hit this after deleting that file. The tool edits it rather than creating it, so put back a file with just the Logging section.

Note: a 401 with no error_description usually means no token arrived at all. Check the header is exactly Bearer plus a space, and wrap client calls in a try-catch block while you debug.

Where to Take It Next with JWT in ASP.NET Core

Swap the in-memory payroll list for a database with the LINQ queries you already know, and move the demo users into ASP.NET Core Identity. Then put an identity provider in front of the API when real customers sign in.

Every API here targets .NET 10. The What is new in .NET 10 roundup lists the other runtime and ASP.NET Core changes worth knowing.

A few more pages that fit this one:

• Every ASP.NET Core tutorial on AspDotnetHelp
• Move an older API from .NET 8 to .NET 10
• .NET 8 and .NET 9 end-of-support dates
• Interfaces in C# for a token service

JWT only works when UseAuthentication runs before UseAuthorization, and that order trips up a lot of people. I explain the whole pipeline, including the recommended order and how to write your own, in middleware in ASP.NET Core.

Frequently Asked Questions

Use a class for objects with identity and changing state, and a struct only for tiny values.

I ran all three on one Austin, TX address on .NET 10. The class called two identical addresses unequal, the record and struct didn’t, and a million structs allocated 15.3 MB versus 38.1 MB.

Record vs Class vs Struct in C# at a Glance

A record isn’t a third kind of type. It’s a modifier: record (or record class) is a reference type, and record struct is a value type. The compiler adds value equality, ToString, with and deconstruction on top.

Every test below uses one sample: a shipping address in Austin, TX 78701, declared four ways. If plain structs are new to you, start with structures in C#.

Record vs Class Equality: Does == Compare Values?

Only on records. Here are two identical addresses per type, compared with == and Equals:

var c1 = new AddressClass("Austin", "TX", "78701");
var c2 = new AddressClass("Austin", "TX", "78701");
var r1 = new AddressRecord("Austin", "TX", "78701");
var r2 = new AddressRecord("Austin", "TX", "78701");
var s1 = new AddressStruct("Austin", "TX", "78701");
var s2 = new AddressStruct("Austin", "TX", "78701");
var rs1 = new AddressRecordStruct("Austin", "TX", "78701");
var rs2 = new AddressRecordStruct("Austin", "TX", "78701");

Console.WriteLine($"class         == {c1 == c2,-5}  Equals {c1.Equals(c2)}");
Console.WriteLine($"record        == {r1 == r2,-5}  Equals {r1.Equals(r2)}");
Console.WriteLine($"struct        == n/a    Equals {s1.Equals(s2)}");
Console.WriteLine($"record struct == {rs1 == rs2,-5}  Equals {rs1.Equals(rs2)}");

class AddressClass(string city, string state, string zip)
{
    public string City => city; public string State => state; public string Zip => zip;
}
record AddressRecord(string City, string State, string Zip);
struct AddressStruct(string city, string state, string zip)
{
    public string City = city, State = state, Zip = zip;
}
record struct AddressRecordStruct(string City, string State, string Zip);

Output:

class         == False  Equals False
record        == True   Equals True
struct        == n/a    Equals True
record struct == True   Equals True

The class printed False because it compares references, and c1 and c2 are two objects. The record compared City, State and Zip and printed True.

The plain struct’s Equals also said True, but == doesn’t exist on a struct until you write it, and ValueType.Equals uses reflection. A record struct gets a compiler-generated == and IEquatable<T> for free.

Record Class vs Record Struct vs Readonly Record Struct

Same address values, now as the three record flavors. Watch what assignment copies and what you’re allowed to change:

var rc = new AddressRecord("Austin", "TX", "78701");
var rcAlias = rc;                       // copies the reference
Console.WriteLine($"record class:    same object {ReferenceEquals(rc, rcAlias)}");

var rs = new AddressRecordStruct("Austin", "TX", "78701");
var rsCopy = rs;                        // copies the whole value
rsCopy.City = "Dallas";                 // allowed: positional props are get; set;
Console.WriteLine($"record struct:   {rs.City} / {rsCopy.City}");

var ro = new AddressReadonly("Austin", "TX", "78701");
// ro.City = "Dallas";                  // CS8852: init-only property
Console.WriteLine($"readonly record struct: {ro}");

record AddressRecord(string City, string State, string Zip);
record struct AddressRecordStruct(string City, string State, string Zip);
readonly record struct AddressReadonly(string City, string State, string Zip);

Output:

record class:    same object True
record struct:   Austin / Dallas
readonly record struct: AddressReadonly { City = Austin, State = TX, Zip = 78701 }

Assigning the record class copied the reference, so both variables point at one object. Assigning the record struct copied the value, so changing the copy to Dallas left the original in Austin.

Positional properties are init-only in a record class and a readonly record struct (the ro.City line fails with CS8852), but read-write in a plain record struct. I default to readonly record struct.

Record ToString Output and Positional Deconstruction

Positional syntax (record AddressRecord(string City, string State, string Zip)) writes the primary constructor, the properties and a Deconstruct method for you:

var home = new AddressRecord("Austin", "TX", "78701");
Console.WriteLine(home);
Console.WriteLine(new AddressClass { City = "Austin" });

var (city, state, zip) = home;          // positional records get Deconstruct
Console.WriteLine($"{city}, {state} {zip}");

record AddressRecord(string City, string State, string Zip);
class AddressClass { public string? City; }

Output:

AddressRecord { City = Austin, State = TX, Zip = 78701 }
AddressClass
Austin, TX 78701

The record printed every property in Type { Name = Value } form; the class printed only its type name, so you’d override ToString in C# yourself for readable logs.

With Expressions: Copying a Record (and the Shallow Copy Gotcha)

Records are meant to be changed by copying. A with expression clones the record and sets only the properties you list. Same address values, plus a shipment that holds a list:

var home = new AddressRecord("Austin", "TX", "78701");
var office = home with { City = "Dallas", Zip = "75201" };
Console.WriteLine(home);
Console.WriteLine(office);
Console.WriteLine($"Equal: {home == office}");

var order = new Shipment(1001, ["Tent", "Lantern"]);
var reship = order with { Id = 1002 };          // shallow copy
reship.Items.Add("Cooler");
Console.WriteLine($"Order 1001 items: {string.Join(", ", order.Items)}");

var safe = order with { Id = 1003, Items = [.. order.Items] };
safe.Items.Add("Stove");
Console.WriteLine($"Order 1001 items: {order.Items.Count}, 1003: {safe.Items.Count}");

record AddressRecord(string City, string State, string Zip);
record Shipment(int Id, List<string> Items);

Output:

AddressRecord { City = Austin, State = TX, Zip = 78701 }
AddressRecord { City = Dallas, State = TX, Zip = 75201 }
Equal: False
Order 1001 items: Tent, Lantern, Cooler
Order 1001 items: 3, 1003: 4

The Dallas copy left Austin alone. The shipment is the trap: order 1001 suddenly had a Cooler it never ordered.

with copies references, not the objects behind them, so both records shared one List<string>. Copying the list in the same expression (Items = [.. order.Items]) gave order 1003 its own four items.

Record Inheritance: Records Can’t Inherit From Classes

Record classes support inheritance in C#, but only with other records. Same Austin data, now with a business address that adds a company name:

Address home = new Address("Austin", "TX", "78701");
Address dock = new BusinessAddress("Austin", "TX", "78701", "Lone Star Outfitters");

Console.WriteLine(dock);
Console.WriteLine($"Same values, different types: {home == dock}");
Console.WriteLine($"dock is Address: {dock is Address}");

record Address(string City, string State, string Zip);
record BusinessAddress(string City, string State, string Zip, string Company)
    : Address(City, State, Zip);

Output:

BusinessAddress { City = Austin, State = TX, Zip = 78701, Company = Lone Star Outfitters }
Same values, different types: False
dock is Address: True

The derived ToString included the base properties. Equality also checks the runtime type, so two addresses with the same city, state and ZIP weren’t equal.

A record can’t inherit from a class, and a class can’t inherit from a record. I tried it and got CS8864: Records may only inherit from object or another record. Structs and record structs can’t inherit at all.

Record vs Class vs Struct Performance and Memory

This test fills an array with 1,000,000 addresses per type. GC.GetAllocatedBytesForCurrentThread counts the bytes and Stopwatch the time:

using System.Diagnostics;
using System.Runtime.CompilerServices;

const int N = 1_000_000;
Console.WriteLine($"struct size: {Unsafe.SizeOf<AddrStruct>()} bytes");
Run("class ", () => { var a = new AddrClass[N]; for (int i = 0; i < N; i++) a[i] = new("Austin", i); });
Run("record", () => { var a = new AddrRecord[N]; for (int i = 0; i < N; i++) a[i] = new("Austin", i); });
Run("struct", () => { var a = new AddrStruct[N]; for (int i = 0; i < N; i++) a[i] = new("Austin", i); });
Run("boxed ", () => { var a = new object[N]; for (int i = 0; i < N; i++) a[i] = new AddrStruct("Austin", i); });

static void Run(string name, Action fill)
{
    fill();                                           // warm-up
    long start = GC.GetAllocatedBytesForCurrentThread();
    var sw = Stopwatch.StartNew(); fill();
    double mb = (GC.GetAllocatedBytesForCurrentThread() - start) / 1048576.0;
    Console.WriteLine($"{name}  {mb,6:F1} MB  {sw.ElapsedMilliseconds,3} ms");
}
class AddrClass(string city, int zip) { public string City = city; public int Zip = zip; }
record AddrRecord(string City, int Zip);
readonly record struct AddrStruct(string City, int Zip);

Output:

struct size: 16 bytes
class     38.1 MB  173 ms
record    38.1 MB  179 ms
struct    15.3 MB   76 ms
boxed     38.1 MB  175 ms

Class and record allocated the same 38.1 MB, so a record costs nothing extra (the millisecond gap between them changes every run). The struct array took 15.3 MB in 76 ms, because the values sit inline with no object headers.

Storing the same structs as object boxed every one and allocated 38.1 MB in 175 ms. That’s why boxing and unboxing matters when you pick a struct.

This struct is 16 bytes, and every assignment or method call copies all of it, where a class copies an 8-byte reference. Microsoft’s guideline keeps structs under 16 bytes and immutable, so this one is right at the line.

Records as DTOs: ASP.NET Core and System.Text.Json

Records are my default for request and response bodies. ASP.NET Core binds JSON with System.Text.Json, which calls the record’s constructor by parameter name:

#:property PublishAot=false
using System.Text.Json;

var web = new JsonSerializerOptions(JsonSerializerDefaults.Web);
var dto = new AddressDto("Austin", "TX", "78701");

string json = JsonSerializer.Serialize(dto, web);
Console.WriteLine(json);

var back = JsonSerializer.Deserialize<AddressDto>(json, web);
Console.WriteLine(back);
Console.WriteLine($"Round trip equal: {dto == back}");

record AddressDto(string City, string State, string Zip);

Output:

{"city":"Austin","state":"TX","zip":"78701"}
AddressDto { City = Austin, State = TX, Zip = 78701 }
Round trip equal: True

The record serialized to {"city":"Austin","state":"TX","zip":"78701"} and came back equal to the original, which also makes DTOs easy to assert in tests.

Important: file-based apps publish as native AOT by default, which turns off reflection-based JSON. The #:property PublishAot=false line switches that off.

Should EF Core Entities Be Records or Classes?

Classes. Microsoft Learn says EF Core relies on reference equality to keep one instance per entity, so records and record structs aren’t appropriate as entity types. EF Core also doesn’t support updating immutable entities.

In my ASP.NET Core Web API CRUD with EF Core build, the entity is a class and the API contracts are records.

When to Use a Record, a Class or a Struct

For that last row, a tuple in C# is lighter than any declared type. Once the data leaves the method, I promote it to a record.

Classes compare identity, records compare values, structs copy values. Pick by how equality and copying should behave; a record and a class cost the same.

Keep going with these:

• Query lists of records with LINQ
• Abstract classes for shared behavior
• New C# 14 features for your types
• All C# tutorials on aspdotnethelp.com

Records also shine with positional patterns, since you can deconstruct them right inside a switch expression. I show that, along with property and list patterns, in pattern matching in C# with is and switch expressions.

Frequently Asked Questions