DEV Community: Softinbit

50 Free Developer Tools That Run in Your Browser, Built for .NET Work

Softinbit — Thu, 12 Nov 2026 11:19:50 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It was first published on softinbit.com.

It is a familiar moment. A production exception lands in the team channel, and someone pastes it into the first "stack trace formatter" a search engine returns. Ten minutes later, someone else pastes a JWT into an online decoder, and a connection string with a password into a "connection string validator".

Every one of those sites received data that should never have left the company.

That is why we built SoftInBit Dev Tools: tools we use in our own .NET work, where the processing happens in your browser tab. Paste a token, a log file or an execution plan, and nothing is uploaded. Every tool page shows a Runs locally · nothing uploaded badge, and that is a design rule, not a slogan.

What "runs locally" means

Your input stays in the tab. Formatting, decoding, hashing, diffing and validation all run as JavaScript in your browser. There is no backend that receives your data.
Some tools load an open-source library (for example YAML, SQL formatting or QR codes) from a public CDN the first time you open them. That download is code coming to you; your input does not go anywhere.
Share links keep their state after the #. Tools that offer a share link put the state in the URL fragment, which browsers never send to the server. Still, don't share a link that contains a secret.
The site counts page views, like any website. What you paste is not part of that.

Built for .NET work

These are the tools you won't find on a generic "online JSON formatter" site.

.NET Stack Trace Cleaner

Paste a raw exception from a log, a test runner or a crash report. The tool:

splits it into the outer exception and every inner exception,
removes compiler noise from async methods and lambdas (<>c__DisplayClass, MoveNext, state machines),
collapses framework frames so only your code stands out,
and points at the likely origin: the first frame in your own code under the root cause.

In the example above, a 40-line wall of text becomes one line: the SqlException started in OrderRepository.AddAsync, at OrderRepository.cs:58. The result can be copied as Markdown for a ticket or a pull request.

👉 Clean up your own stack trace

SQL Server Execution Plan Viewer

Paste the XML of an estimated or actual execution plan (or open a .sqlplan file from SSMS). You get the operator tree and a list of findings ranked by how much they matter, each with an explanation:

implicit conversions that prevent an index seek,
key lookups that run thousands of times,
plans compiled for different parameter values (parameter sniffing),
row estimates that are wildly off, memory grants, spills and missing indexes.

Execution plans contain table names, column names and sometimes parameter values. That is exactly the kind of file you don't want to upload to a third-party site.

👉 Analyze an execution plan

Serilog / CLEF Log Viewer

Got a log file from a server, but no Seq or Kibana nearby? Paste or drop Serilog's compact JSON (CLEF) or JSON lines. You can filter by level, search messages and properties, filter by property value (OrderId = 42, Elapsed > 500), narrow down by time on the histogram, and open any entry to see all its properties and the exception.

appsettings.json ⇄ Environment Variables

Moving an app to Docker or Kubernetes means turning nested configuration into Section__Key environment variables, and arrays into Section__0, Section__1. This tool does it in both directions and writes the output in the format you need: .env, Docker Compose, Kubernetes, Azure App Service settings, PowerShell, bash, launchSettings.json or dotnet user-secrets commands.

It also flags keys that look like secrets (connection strings, signing keys) and tells you to keep them out of source control.

curl to C# HttpClient

Copy a request from your browser's network tab or an API's documentation as curl, paste it, and get HttpClient code for modern .NET: plain, or as a typed client registered with AddHttpClient. Form bodies, JSON bodies, headers and authentication are converted, and the notes warn you when the request contains credentials that should come from configuration instead.

JSON to C# Classes

Paste a JSON response and get records or classes ready for System.Text.Json. You choose the root type name, namespace, property naming, collection type and number types. [JsonPropertyName] attributes are added only where the JSON name differs from the C# name, and dates and GUIDs are detected.

JWT Decoder & Verifier

Paste a token to see the header and payload, every claim explained, and the expiry in plain words ("valid, expires in 55 min"). You can verify the signature with a shared secret or a public key, and that check also happens locally. If you are issuing tokens yourself, Issuing and Validating JWT Access Tokens in ASP.NET Core shows the server side.

Connection String Builder & Parser

Paste any SQL Server, PostgreSQL, MySQL or similar connection string. Every key is shown with its meaning, and risky settings are flagged: TrustServerCertificate=True in production, a missing Application Name, a plain-text password. You can edit the fields and copy the result as a connection string, an appsettings.json snippet, environment variables or C#. The password is hidden on screen by default.

The everyday tools

These are the tools almost every developer opens every week. Here they all work offline from your data, too.

Text Compare

Diff two texts with word-level highlights, side by side or inline. Ignore whitespace or case, collapse unchanged lines, jump between changes, and merge a change from one side to the other with one click.

Regex Tester

JavaScript regular expressions with live matching, named groups, a replace preview and a library of common patterns (email, URL, GUID, ISO date, IP address). A backtracking guard stops patterns that would freeze the tab.

And the rest

Formatters: JSON Formatter & Validator with a tree view and auto-fix, SQL Formatter for T-SQL and PostgreSQL, XML Formatter & XPath Tester, and JavaScript, HTML and CSS beautifiers.
Encoders and decoders: Base64, URL encoding, HTML entities, Gzip and deflate, and an X.509 Certificate Decoder for PEM, DER and certificate chains.
Generators: UUID v4 and v7, GUID and ULID, hashes and checksums, passwords, QR codes, lorem ipsum, a Mock Data Generator that outputs JSON, CSV, SQL INSERT or C#, and an RSA & ECDSA Key Pair Generator with PEM, JWK and the XML format .NET understands.
Converters: Unix timestamps, including .NET ticks, a Cron Expression Parser that explains a schedule in plain English, JSON ⇄ YAML, JSON ⇄ CSV, and number bases.
Testers: JSON Schema validation and generation, JSONPath, and an XML Schema (XSD) Validator that runs the real libxml2 engine in your browser.
Text, web and graphics: list compare, a Markdown preview, a Unicode and invisible character inspector, a CIDR / subnet calculator, a color converter with WCAG contrast checks, an image converter and a color blindness simulator.
For Turkish projects: a TCKN, VKN and IBAN validator that explains why a number fails and generates valid test values with C# code.

Small things that save time

Press / on the tools page to search, and Ctrl+Enter (Cmd+Enter on a Mac) to run a tool's main action.
Focus mode hides everything except the tool.
Most tools have an Example button, so you can see what they do before you paste your own data.
The tool interfaces are available in English, Turkish, German, Spanish and French, and they all work in dark mode.

What's next

We add tools when our own projects need them. If there is a tool you keep searching for, especially one for .NET, SQL Server or Azure work, tell us and it may be the next one.

Start at softinbit.com/tools.

Originally published at softinbit.com. New articles and tools by email: subscribe.

Thinking Like a Programmer: Turning a Vague Request Into Working Code

Softinbit — Fri, 06 Nov 2026 06:29:03 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series Zero to Full-Stack .NET.

Go from a one-sentence request to a small, tested program without guessing what the business meant.

Part 1 of the "Zero to Full-Stack .NET" series. Section: Getting Started.

TL;DR

Turn vague product requests into precise clarifying questions and plain-language steps before touching code.

Break logic into small, single-purpose functions, test edge cases (nulls, time zones, paid boundaries), and avoid embedding clock calls inside business logic.

Master practical day-one debugging skills: isolating stack traces, setting breakpoints, using watch expressions, and effective error searching.

Level: Beginner · Prerequisites: A basic .NET developer environment installed and a willingness to ask questions before coding · Reading time: 10 min

The product owner stops by your desk: "Can you send a reminder to customers whose invoices are overdue?" She leaves. You open the editor and stare at an empty file. Where does the code even start? What is an invoice in this system? What does overdue mean? Email or SMS?

Many beginners start typing anyway. Two hours later there is a loop, a half-written email template, and a growing feeling that the thing being built is not the thing that was asked for. The problem is not your C#. The problem is that the request was never turned into something precise enough to code.

This article walks through that translation with a real example, ends with a console app you can run, and then covers the three skills that make the difference on day one: reading an error, using the debugger, and searching for the right thing.

What you will be able to do after this

Turn a vague sentence into a list of clarifying questions and a plain-language plan
Break the plan into small C# functions that each do one thing
Handle the edge cases the request did not mention (missing dates, paid invoices, time zones)
Read a stack trace and find the line that matters
Use breakpoints, step over, and the watch window to see what your code actually does

Ask before you type

A request like "remind customers with overdue invoices" hides at least five decisions. Write them down and ask. Here are the questions and the answers the product owner gave:

Question	Answer
What does "overdue" mean?	The due date has passed and we allow three days of grace
Which customers?	Anyone with at least one unpaid overdue invoice
What if the invoice was paid after the due date?	Skip it, paid is paid
Invoices without a due date?	Those are drafts, ignore them
How often and through which channel?	Once a day, by email, one email per customer listing all their overdue invoices

Ten minutes of questions saved a day of rework. Notice that "one email per customer" changes the shape of the code: you need to group invoices by customer, not send one message per invoice.

Write the steps in plain language

Before any C#, write the algorithm as sentences a non-programmer could check:

Take today's date (in the company's time zone).
Take all invoices.
Keep the ones that are not paid, have a due date, and whose due date is more than three days ago.
Group them by customer.
For each customer, build one message listing the invoices and the total.
Send the messages.

Each line becomes one function or one LINQ call. If a line is hard to write as a sentence, it will be hard to write as code; ask more questions.

Turn each step into a small function

Create a console app and paste the code below into Program.cs. It is complete: it uses an in-memory list instead of a database so you can run it right now. DateOnly is used because an invoice is due on a day, not at a time.

dotnet new console -n Store.Reminders
cd Store.Reminders

using System.Globalization;

var today = new DateOnly(2026, 10, 12);

var invoices = new List<Invoice>
{
    new(1001, "Ayşe Yılmaz", "ayse@example.com", 1250.00m, new DateOnly(2026, 9, 20), PaidOn: null),
    new(1002, "Mehmet Kaya", "mehmet@example.com", 480.50m, new DateOnly(2026, 10, 1), PaidOn: new DateOnly(2026, 10, 3)),
    new(1003, "Zeynep Demir", "zeynep@example.com", 3200.00m, new DateOnly(2026, 10, 20), PaidOn: null),
    new(1004, "Can Öztürk", "can@example.com", 99.90m, DueDate: null, PaidOn: null),
    new(1005, "Ayşe Yılmaz", "ayse@example.com", 700.00m, new DateOnly(2026, 10, 8), PaidOn: null),
};

var overdue = FindOverdue(invoices, today, graceDays: 3);

foreach (var customerInvoices in overdue.GroupBy(i => i.CustomerEmail))
{
    var message = BuildReminder(customerInvoices.Key, customerInvoices.ToList(), today);
    Console.WriteLine(message);
    Console.WriteLine(new string('-', 40));
}

// Step 3 of the plan: unpaid, has a due date, due date older than the grace period
static List<Invoice> FindOverdue(IEnumerable<Invoice> invoices, DateOnly today, int graceDays)
{
    var cutoff = today.AddDays(-graceDays);

    return invoices
        .Where(i => i.PaidOn is null)
        .Where(i => i.DueDate is not null && i.DueDate.Value < cutoff)
        .OrderBy(i => i.DueDate)
        .ToList();
}

// Step 5 of the plan: one message per customer
static string BuildReminder(string email, List<Invoice> invoices, DateOnly today)
{
    var tr = CultureInfo.GetCultureInfo("tr-TR");
    var total = invoices.Sum(i => i.Amount);

    var lines = invoices.Select(i =>
    {
        var due = i.DueDate!.Value; // FindOverdue guarantees a due date
        var daysLate = today.DayNumber - due.DayNumber;
        return $"  #{i.Number}: {i.Amount.ToString("N2", tr)} TL due {due:yyyy-MM-dd} ({daysLate} days late)";
    });

    return $"""
        To: {email}
        Subject: {invoices.Count} overdue invoice(s), total {total.ToString("N2", tr)} TL

        {string.Join(Environment.NewLine, lines)}
        """;
}

record Invoice(
    int Number,
    string CustomerName,
    string CustomerEmail,
    decimal Amount,
    DateOnly? DueDate,
    DateOnly? PaidOn);

Run it with dotnet run:

To: ayse@example.com
Subject: 2 overdue invoice(s), total 1.950,00 TL

  #1001: 1.250,00 TL due 2026-09-20 (22 days late)
  #1005: 700,00 TL due 2026-10-08 (4 days late)
----------------------------------------

Map the code back to the plan. FindOverdue is step 3. It receives the list, today's date, and the grace period as parameters; it never reads the clock itself, which is what makes it testable: you can pass any "today". GroupBy is step 4. BuildReminder is step 5. Step 6, sending, is deliberately missing; it will be an email service later, and the first version proves the logic without touching a mail server.

Each function is small enough to explain in one sentence. That is the test for whether you have split the problem enough.

Handle the edge cases the request did not mention

The sample data already contains the traps:

Invoice 1002 was paid late. PaidOn is null filters it out. Without that line, a customer who already paid gets a reminder, and you get an angry phone call.
Invoice 1004 has no due date. DueDate is not null skips it. Without it, DueDate.Value throws InvalidOperationException at runtime, usually on the one record you did not test with.
Invoice 1005 is four days late, just past the three-day grace period. Boundary values are where off-by-one bugs live. Change today to 2026-10-11 and confirm 1005 disappears from the output.

"Today" is the subtle one. DateTime.Now on a server in a Frankfurt data centre is not today in Istanbul at 01:00. For now, compute today in the company's time zone and pass it in:

var istanbul = TimeZoneInfo.FindSystemTimeZoneById("Europe/Istanbul");
var today = DateOnly.FromDateTime(TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, istanbul));

Time zones get their own article later in the series. The habit to keep is that business functions receive today as a parameter and never call the clock themselves.

Test with tiny data, then iterate

The five-invoice list is the test. Each invoice exists to prove one rule: one is plainly overdue, one is paid, one is in the future, one has no due date, one sits on the boundary. When you later move the data to SQL Server and the sending to an email service, FindOverdue and BuildReminder do not change, and the same five records become your first unit tests.

Then iterate. The product owner reads the message, asks for the customer's name in a greeting line, and you add one parameter to BuildReminder. Small functions make small changes.

Reading an error without panicking

Suppose a colleague removes the i.DueDate is not null && part of the filter. The next run prints something like this (your line numbers and the compiler-generated names will differ):

Unhandled exception. System.InvalidOperationException: Nullable object must have a value.
   at System.Nullable`1.get_Value()
   at Program.<>c__DisplayClass0_0.<<Main>$>b__1(Invoice i) in C:\src\Store.Reminders\Program.cs:line 30
   at System.Linq.Enumerable.WhereEnumerableIterator`1.MoveNext()
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Program.<<Main>$>g__FindOverdue|0_0(IEnumerable`1 invoices, DateOnly today, Int32 graceDays) in C:\src\Store.Reminders\Program.cs:line 28
   at Program.<Main>$(String[] args) in C:\src\Store.Reminders\Program.cs:line 14

Read it in this order:

The first line is the exception type and message. "Nullable object must have a value" means something called .Value on a null.
The lines starting with at are the stack trace, newest call first. The top frame is inside .NET itself. Skip every frame that is not in your code.
The first frame with a path to your file is the one to open: Program.cs:line 30. That is the lambda inside Where, and that is where the fix goes.
Lines that mention System.Linq or System.Collections are plumbing between your frames. They tell you the path the call took, not where the bug is.

Using the debugger instead of Console.WriteLine

Set a breakpoint by clicking the margin next to var cutoff = ... (or press F9 on that line). Press F5. Execution stops there, and hovering over any variable shows its value.
Step over (F10) runs the current line and stops at the next one. Step into (F11) goes inside a method call. Step out (Shift+F11) finishes the current method and stops in the caller.
The Watch window lets you type cutoff or invoices.Count and keeps the value updated after every step. The Locals window shows everything in scope without typing.
A conditional breakpoint stops only when something is true. Right-click the breakpoint inside the Where lambda, choose Conditions, and enter i.Number == 1004. Now the debugger stops on the invoice you care about instead of 4,000 times.

VS Code with the C# Dev Kit uses the same keys and the same windows under slightly different names.

Searching for an error the right way

Copy the exception type and the message, not your variable names: InvalidOperationException "Nullable object must have a value".
Add the technology: C#, EF Core, or ASP.NET Core, plus the version if you suspect behaviour changed between versions.
Prefer learn.microsoft.com, the library's GitHub issues, and Stack Overflow answers with recent dates.
Read the question before the answer. Half the time the asker's situation differs from yours in the one detail that matters.
When an AI assistant suggests code, run it against the five-invoice data set before trusting it.

Who you work with

The business analyst (or product owner) writes the request and the acceptance criteria. They expect you to ask questions early, in writing, and to say when something is ambiguous rather than guess and deliver the wrong thing confidently.
The tester (QA, quality assurance) checks the result against the acceptance criteria and hunts for edge cases. They expect a note on what changed, how to reproduce it, and which cases you already covered. Give them the five-invoice list; they will add five more.
Other developers review your code and maintain it later. They expect small functions, names that say what things are, and a pull request they can read in ten minutes.

Common mistakes

Starting to code before the request is precise. You build the wrong thing well. Write the questions table first and get answers in writing.
Reading the clock inside business logic. DateTime.Now inside FindOverdue makes it untestable and time zone dependent. Pass today in as a parameter.
Using the null-forgiving operator to silence a nullable warning instead of filtering. The runtime exception arrives on production data. Filter with is not null and let the compiler stop warning on its own.
One giant method that selects, formats, and sends. You cannot test the selection without sending emails. Split by plan step.
Testing only the happy path. Include a paid invoice, a missing date, a future date, and a boundary record in the first data set.
Searching with your own variable names or file paths in the query. Nobody else has Store.Reminders. Search the message.
Reading only the first line of a stack trace. The line number of your bug is a few lines down.

Checklist

Clarifying questions and their answers written down before coding
Plan written as numbered plain-language steps
One function per step, each explainable in a sentence
today and other external inputs passed as parameters
Test data includes null, paid, future, and boundary cases
Expected output written down before running
Stack trace read down to the first frame in your own file
Breakpoint and Watch window, not Console.WriteLine, used to inspect state

What's next

The next article, "Git for Daily Work: Branches, Pull Requests, and Fixing Mistakes", puts this program under version control and shows how to share it without overwriting anyone's work. After that, Part 2 starts with "C# Types in Practice: Value vs Reference, decimal vs double, and Nullable", which explains why the amounts above are decimal and the dates are DateOnly?.

Originally published at www.softinbit.com. Part of Zero to Full-Stack .NET.

MassTransit vs Wolverine vs Raw RabbitMQ.Client After the MassTransit License Change

Softinbit — Thu, 05 Nov 2026 11:33:58 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series The .NET Field Guide.

Decide whether to license MassTransit v9, stay on v8 for now, move to Wolverine, or write the RabbitMQ code yourself.

Part of "The .NET Field Guide". Section: Comparisons.

TL;DR

MassTransit v9 moved to a commercial license requiring runtime keys. If you only publish and consume events, you do not need to blindly pay or panic.

Compare three real paths for the same order-processing flow: keep MassTransit (v8 open source or v9 licensed), migrate to MIT-licensed Wolverine 6, or write lightweight async consumers with RabbitMQ.Client 7.

Complete benchmarks, topology setups, retry/dead-letter policies, and an outbox comparison to pick the right option for your team.

Level: Intermediate · Prerequisites: Basic understanding of message queues and RabbitMQ, ASP.NET Core dependency injection · Reading time: 14 min

Dependabot opened a pull request this morning: MassTransit.RabbitMQ 8.5.11 to 9.2.3. The build is green, but the MassTransit docs now say v9 is a commercial product and that the license key must be available at runtime on every machine that runs MassTransit code, developer laptops included. Your Store.Api uses MassTransit for exactly one flow: when an order is placed, publish OrderPlaced, and a consumer reserves stock.

You can keep MassTransit (v8 for now, or v9 with a license), move to Wolverine, or use RabbitMQ.Client directly. This article builds the same flow in all three, with retries, an error queue, and idempotent handling.

The short answer

Choose MassTransit v9 with a license when you use sagas, routing slips, the transactional outbox, or several transports, and the subscription cost is smaller than the rewrite. Small organizations should check whether they qualify for the full discount.
Choose MassTransit v8 when you need the current code to keep running this quarter, and you put a dated migration or licensing decision on the roadmap.
Choose Wolverine when you want an MIT-licensed framework with retries, dead-letter queues, an inbox and outbox, and convention-based handlers, and you run on .NET 9 or 10.
Choose raw RabbitMQ.Client when you have one or two message types, want no framework dependency, and accept that you own retries, error queues, serialization, and topology.

What is being compared

MassTransit is a message bus framework for .NET with consumers, sagas, retries, an outbox, and testing helpers. The current major version is 9 (9.2.3 on NuGet in October 2026), sold by Massient, Inc., the company created by founder Chris Patterson. Version 9 needs a license; the license terms say v8 and earlier "remain free and open source under their original licenses" (Apache 2.0) but are unsupported under the commercial agreement. Version 8 still ships patch releases (8.5.11 at the end of September 2026).

Wolverine (WolverineFx) is a messaging and command-handling framework from JasperFx Software, the team behind Marten. The current major is 6 (6.50.0), released under the MIT license. Wolverine 6 targets .NET 9 and .NET 10 only; teams on .NET 8 must stay on 5.x.

RabbitMQ.Client is the official .NET client for RabbitMQ, maintained by the RabbitMQ core team. The current major is 7 (7.2.2), dual-licensed under Apache 2.0 and the Mozilla Public License 2.0. Version 7 made the API fully asynchronous.

The same task in each option

The task: POST /api/orders/{id}/placed-event publishes OrderPlaced. A consumer reserves stock for each line. Transient failures retry three times with a delay. Permanent failures (a product that does not exist) go straight to an error queue. A redelivered message never reserves stock twice.

Start RabbitMQ locally:

docker run -d --name store-rabbit -p 5672:5672 -p 15672:15672 rabbitmq:4-management

Add the settings to appsettings.Development.json:

{
  "RabbitMq": { "Host": "localhost", "Username": "guest", "Password": "guest" }
}

Shared code used by all three options

The contract, the idempotency table, and the business logic are identical everywhere.

// File: Orders/Messaging/OrderPlaced.cs
namespace Store.Api.Orders.Messaging;

public sealed record OrderPlaced(int OrderId, string UserId, DateTime PlacedAtUtc, IReadOnlyList<OrderPlacedLine> Lines);

public sealed record OrderPlacedLine(int ProductId, int Quantity);

public interface IOrderEvents
{
    Task PublishOrderPlacedAsync(OrderPlaced message, CancellationToken ct);
}

public sealed class ProcessedMessage
{
    public string Consumer { get; set; } = "";
    public string MessageKey { get; set; } = "";
    public DateTime ProcessedAtUtc { get; set; }
}

// File: Data/AppDbContext.cs (additions; add using Store.Api.Orders.Messaging;)
public DbSet<ProcessedMessage> ProcessedMessages => Set<ProcessedMessage>();

// Inside OnModelCreating:
modelBuilder.Entity<ProcessedMessage>(e =>
{
    e.HasKey(p => new { p.Consumer, p.MessageKey });
    e.Property(p => p.Consumer).HasMaxLength(100);
    e.Property(p => p.MessageKey).HasMaxLength(100);
});

// File: Orders/Messaging/StockReservationService.cs
using Microsoft.EntityFrameworkCore;
using Store.Api.Data;

namespace Store.Api.Orders.Messaging;

public sealed class StockReservationService(AppDbContext db, TimeProvider time, ILogger<StockReservationService> logger)
{
    private const string ConsumerName = "reserve-stock";

    public async Task ReserveAsync(OrderPlaced message, CancellationToken ct)
    {
        var key = $"order-{message.OrderId}";
        if (await db.ProcessedMessages.AnyAsync(p => p.Consumer == ConsumerName && p.MessageKey == key, ct))
        {
            logger.LogInformation("Stock for order {OrderId} already reserved, skipping duplicate", message.OrderId);
            return;
        }

        await using var tx = await db.Database.BeginTransactionAsync(ct);
        foreach (var line in message.Lines)
        {
            // Atomic decrement: two orders reserving the same product cannot overwrite each other.
            var updated = await db.Products.Where(p => p.Id == line.ProductId)
                .ExecuteUpdateAsync(s => s.SetProperty(p => p.Stock, p => p.Stock - line.Quantity), ct);
            if (updated == 0)
                throw new InvalidOperationException($"Product {line.ProductId} does not exist.");
        }

        db.ProcessedMessages.Add(new ProcessedMessage
        {
            Consumer = ConsumerName,
            MessageKey = key,
            ProcessedAtUtc = time.GetUtcNow().UtcDateTime
        });
        await db.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);
    }
}

The stock updates and the ProcessedMessages row commit in one transaction, so they succeed or fail together. If two copies of the same message race, the composite primary key rejects the second insert with a DbUpdateException, the retry policy runs it again, and the second attempt sees the row and skips. That is why the key is the business identity (order-42) and not a transport message id.

// File: Orders/OrderEventsController.cs
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Store.Api.Data;
using Store.Api.Orders.Messaging;

namespace Store.Api.Orders;

[ApiController]
[Route("api/orders")]
public sealed class OrderEventsController(AppDbContext db, IOrderEvents events) : ControllerBase
{
    [HttpPost("{id:int}/placed-event")]
    public async Task<IActionResult> PublishPlaced(int id, CancellationToken ct)
    {
        var order = await db.Orders.AsNoTracking().Include(o => o.Lines).FirstOrDefaultAsync(o => o.Id == id, ct);
        if (order is null) return NotFound();

        var lines = order.Lines.Select(l => new OrderPlacedLine(l.ProductId, l.Quantity)).ToList();
        await events.PublishOrderPlacedAsync(new OrderPlaced(order.Id, order.UserId, order.CreatedAtUtc, lines), ct);
        return Accepted();
    }
}

All three options also need builder.Services.AddSingleton(TimeProvider.System); and builder.Services.AddScoped<StockReservationService>(); in Program.cs.

MassTransit v8

dotnet add package MassTransit.RabbitMQ --version 8.5.11

Pin the version. A plain dotnet add package MassTransit.RabbitMQ now installs v9.

// File: Orders/Messaging/MassTransitBus/ReserveStockConsumer.cs
using MassTransit;

namespace Store.Api.Orders.Messaging.MassTransitBus;

public sealed class ReserveStockConsumer(StockReservationService reservations) : IConsumer<OrderPlaced>
{
    public Task Consume(ConsumeContext<OrderPlaced> context) =>
        reservations.ReserveAsync(context.Message, context.CancellationToken);
}

public sealed class ReserveStockConsumerDefinition : ConsumerDefinition<ReserveStockConsumer>
{
    public ReserveStockConsumerDefinition()
    {
        EndpointName = "order-placed.reserve-stock";
        ConcurrentMessageLimit = 10;
    }

    protected override void ConfigureConsumer(IReceiveEndpointConfigurator endpointConfigurator,
        IConsumerConfigurator<ReserveStockConsumer> consumerConfigurator, IRegistrationContext context)
    {
        endpointConfigurator.UseMessageRetry(r =>
        {
            r.Ignore<InvalidOperationException>();
            r.Intervals(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(15));
        });
    }
}

public sealed class MassTransitOrderEvents(IPublishEndpoint publishEndpoint) : IOrderEvents
{
    public Task PublishOrderPlacedAsync(OrderPlaced message, CancellationToken ct) =>
        publishEndpoint.Publish(message, ct);
}

// Program.cs, before builder.Build() (add using MassTransit; and using Store.Api.Orders.Messaging.MassTransitBus;)
var rabbit = builder.Configuration.GetSection("RabbitMq");
builder.Services.AddScoped<IOrderEvents, MassTransitOrderEvents>();
builder.Services.AddMassTransit(x =>
{
    x.AddConsumer<ReserveStockConsumer, ReserveStockConsumerDefinition>();
    x.UsingRabbitMq((context, cfg) =>
    {
        cfg.Host(rabbit["Host"]!, "/", h =>
        {
            h.Username(rabbit["Username"]!);
            h.Password(rabbit["Password"]!);
        });
        cfg.ConfigureEndpoints(context);
    });
});

ConfigureEndpoints creates the queue order-placed.reserve-stock, an exchange per message type, and the bindings. You never declare topology.
UseMessageRetry retries in memory three times. Ignore<InvalidOperationException>() skips retries for the permanent error.
When retries run out, MassTransit moves the message to order-placed.reserve-stock_error with the exception details in headers, and publishes a Fault<OrderPlaced> you can consume.
Delayed redelivery (minutes, not seconds) is a separate feature that needs a message scheduler, such as the RabbitMQ delayed message exchange plugin.

Wolverine

dotnet add package WolverineFx
dotnet add package WolverineFx.RabbitMQ
dotnet add package WolverineFx.RuntimeCompilation

Since 6.0, runtime code generation is opt-in: add WolverineFx.RuntimeCompilation. It registers itself; opts.UseRuntimeCompilation() is needed only when extension auto-discovery is off.

// File: Orders/Messaging/WolverineBus/OrderPlacedHandler.cs
using Wolverine;

namespace Store.Api.Orders.Messaging.WolverineBus;

public sealed class OrderPlacedHandler
{
    public Task Handle(OrderPlaced message, StockReservationService reservations, CancellationToken cancellationToken) =>
        reservations.ReserveAsync(message, cancellationToken);
}

public sealed class WolverineOrderEvents(IMessageBus bus) : IOrderEvents
{
    public Task PublishOrderPlacedAsync(OrderPlaced message, CancellationToken ct) =>
        bus.PublishAsync(message).AsTask();
}

// Program.cs, before builder.Build()
// (add using Wolverine; using Wolverine.ErrorHandling; using Wolverine.RabbitMQ; using Store.Api.Orders.Messaging.WolverineBus;)
var rabbit = builder.Configuration.GetSection("RabbitMq");
builder.Services.AddScoped<IOrderEvents, WolverineOrderEvents>();
builder.Host.UseWolverine(opts =>
{
    opts.UseRuntimeCompilation(); // from WolverineFx.RuntimeCompilation
    opts.UseRabbitMq(f =>
        {
            f.HostName = rabbit["Host"]!;
            f.UserName = rabbit["Username"]!;
            f.Password = rabbit["Password"]!;
        })
        .AutoProvision();

    opts.PublishMessage<OrderPlaced>()
        .ToRabbitExchange("store.orders", exchange => exchange.BindQueue("order-placed.reserve-stock"));

    opts.ListenToRabbitQueue("order-placed.reserve-stock")
        .DeadLetterQueueing(new DeadLetterQueue("order-placed.reserve-stock.error"));

    opts.Policies.OnException<InvalidOperationException>().MoveToErrorQueue();
    opts.Policies.OnAnyException()
        .RetryWithCooldown(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(15))
        .Then.MoveToErrorQueue();
});

No consumer interface. Wolverine finds public classes whose names end in Handler or Consumer and methods named Handle or Consume. Extra parameters (StockReservationService, CancellationToken) are injected per message.
Error rules are checked in order and the first match wins, so the specific rule comes before OnAnyException(). A message that matches no rule goes to the error queue.
By default Wolverine uses RabbitMQ's native dead-letter exchange and a shared wolverine-dead-letter-queue. DeadLetterQueueing gives this queue its own error queue.
Wolverine's durable inbox (with message storage such as WolverineFx.SqlServer) adds deduplication by envelope id. The business-key check above still matters, because a client that publishes the same order twice creates two envelopes.

Raw RabbitMQ.Client 7

dotnet add package RabbitMQ.Client

Now you write what the frameworks did: a long-lived connection, topology, publisher confirms, a consumer loop, and retries. Retries go to a queue with a 10-second message time to live (TTL); when it expires, RabbitMQ dead-letters the message back to the main queue.

// File: Orders/Messaging/RawRabbit/RabbitConnection.cs
using RabbitMQ.Client;

namespace Store.Api.Orders.Messaging.RawRabbit;

public sealed class RabbitConnection(IConfiguration configuration) : IAsyncDisposable
{
    private readonly SemaphoreSlim _gate = new(1, 1);
    private IConnection? _connection;

    public async Task<IConnection> GetAsync(CancellationToken ct)
    {
        if (_connection is not null) return _connection;
        await _gate.WaitAsync(ct);
        try
        {
            var section = configuration.GetSection("RabbitMq");
            _connection ??= await new ConnectionFactory
            {
                HostName = section["Host"]!,
                UserName = section["Username"]!,
                Password = section["Password"]!
            }.CreateConnectionAsync("Store.Api", ct);
            return _connection;
        }
        finally { _gate.Release(); }
    }

    public async ValueTask DisposeAsync()
    {
        if (_connection is not null) await _connection.DisposeAsync();
    }
}

public static class RabbitTopology
{
    public const string Exchange = "store.orders";
    public const string RoutingKey = "order.placed";
    public const string Queue = "order-placed.reserve-stock";
    public const string RetryQueue = Queue + ".retry";
    public const string ErrorQueue = Queue + ".error";

    public static readonly CreateChannelOptions Confirmed =
        new(publisherConfirmationsEnabled: true, publisherConfirmationTrackingEnabled: true);

    public static async Task DeclareAsync(IChannel channel, CancellationToken ct)
    {
        await channel.ExchangeDeclareAsync(Exchange, ExchangeType.Topic, durable: true, cancellationToken: ct);
        await channel.QueueDeclareAsync(Queue, durable: true, exclusive: false, autoDelete: false, cancellationToken: ct);
        await channel.QueueBindAsync(Queue, Exchange, RoutingKey, cancellationToken: ct);
        await channel.QueueDeclareAsync(RetryQueue, durable: true, exclusive: false, autoDelete: false,
            arguments: new Dictionary<string, object?>
            {
                ["x-message-ttl"] = 10_000,
                ["x-dead-letter-exchange"] = "",
                ["x-dead-letter-routing-key"] = Queue
            }, cancellationToken: ct);
        await channel.QueueDeclareAsync(ErrorQueue, durable: true, exclusive: false, autoDelete: false, cancellationToken: ct);
    }
}

// File: Orders/Messaging/RawRabbit/RabbitOrderEvents.cs
using System.Text.Json;
using RabbitMQ.Client;

namespace Store.Api.Orders.Messaging.RawRabbit;

public sealed class RabbitOrderEvents(RabbitConnection rabbit) : IOrderEvents, IAsyncDisposable
{
    private readonly SemaphoreSlim _gate = new(1, 1);
    private IChannel? _channel;

    public async Task PublishOrderPlacedAsync(OrderPlaced message, CancellationToken ct)
    {
        await _gate.WaitAsync(ct);
        try
        {
            if (_channel is null)
            {
                _channel = await (await rabbit.GetAsync(ct)).CreateChannelAsync(RabbitTopology.Confirmed, ct);
                await RabbitTopology.DeclareAsync(_channel, ct);
            }

            var properties = new BasicProperties
            {
                Persistent = true,
                ContentType = "application/json",
                MessageId = $"order-{message.OrderId}",
                Type = nameof(OrderPlaced)
            };
            await _channel.BasicPublishAsync(RabbitTopology.Exchange, RabbitTopology.RoutingKey, mandatory: true,
                basicProperties: properties, body: JsonSerializer.SerializeToUtf8Bytes(message), cancellationToken: ct);
        }
        finally { _gate.Release(); }
    }

    public async ValueTask DisposeAsync()
    {
        if (_channel is not null) await _channel.DisposeAsync();
    }
}

// File: Orders/Messaging/RawRabbit/ReserveStockWorker.cs
using System.Text.Json;
using RabbitMQ.Client;
using RabbitMQ.Client.Events;

namespace Store.Api.Orders.Messaging.RawRabbit;

public sealed class ReserveStockWorker(RabbitConnection rabbit, IServiceScopeFactory scopes,
    ILogger<ReserveStockWorker> logger) : BackgroundService
{
    private const int MaxRetries = 3;
    private const string RetryHeader = "x-retry-count";
    private IChannel? _consumeChannel;
    private IChannel? _publishChannel;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var connection = await rabbit.GetAsync(stoppingToken);
        _publishChannel = await connection.CreateChannelAsync(RabbitTopology.Confirmed, stoppingToken);
        _consumeChannel = await connection.CreateChannelAsync(cancellationToken: stoppingToken);
        await RabbitTopology.DeclareAsync(_consumeChannel, stoppingToken);
        await _consumeChannel.BasicQosAsync(prefetchSize: 0, prefetchCount: 10, global: false, stoppingToken);

        var consumer = new AsyncEventingBasicConsumer(_consumeChannel);
        consumer.ReceivedAsync += HandleAsync;
        await _consumeChannel.BasicConsumeAsync(RabbitTopology.Queue, autoAck: false, consumer, stoppingToken);

        try { await Task.Delay(Timeout.Infinite, stoppingToken); }
        catch (OperationCanceledException) { }
    }

    private async Task HandleAsync(object sender, BasicDeliverEventArgs delivery)
    {
        try
        {
            var message = JsonSerializer.Deserialize<OrderPlaced>(delivery.Body.Span)
                ?? throw new InvalidOperationException("Empty OrderPlaced message.");
            await using var scope = scopes.CreateAsyncScope();
            await scope.ServiceProvider.GetRequiredService<StockReservationService>()
                .ReserveAsync(message, delivery.CancellationToken);
        }
        catch (Exception ex)
        {
            var attempt = ReadRetryCount(delivery.BasicProperties) + 1;
            var permanent = ex is JsonException or InvalidOperationException;
            var target = permanent || attempt > MaxRetries ? RabbitTopology.ErrorQueue : RabbitTopology.RetryQueue;
            logger.LogWarning(ex, "OrderPlaced failed on attempt {Attempt}, moving it to {Queue}", attempt, target);

            var properties = new BasicProperties(delivery.BasicProperties)
            {
                Headers = new Dictionary<string, object?>(delivery.BasicProperties.Headers ?? new Dictionary<string, object?>())
                {
                    [RetryHeader] = attempt,
                    ["x-last-error"] = ex.Message
                }
            };
            await _publishChannel!.BasicPublishAsync("", target, mandatory: true, basicProperties: properties, body: delivery.Body);
        }

        await _consumeChannel!.BasicAckAsync(delivery.DeliveryTag, multiple: false);
    }

    private static int ReadRetryCount(IReadOnlyBasicProperties properties) =>
        properties.Headers is not null && properties.Headers.TryGetValue(RetryHeader, out var value)
            ? value switch { int i => i, long l => (int)l, _ => 0 }
            : 0;
}

// Program.cs, before builder.Build() (add using Store.Api.Orders.Messaging.RawRabbit;)
builder.Services.AddSingleton<RabbitConnection>();
builder.Services.AddSingleton<IOrderEvents, RabbitOrderEvents>();
builder.Services.AddHostedService<ReserveStockWorker>();

Publisher confirms make BasicPublishAsync wait for the broker to accept the message, and mandatory: true turns "no queue bound" into an exception instead of a silent drop.
The failed copy is republished on a separate confirmed channel before the original is acknowledged. If the process dies between those two steps, the message is delivered twice, and the idempotency check absorbs it.

Publish order 42 twice with any option and the logs show the guard working:

info: Store.Api.Orders.Messaging.StockReservationService[0]
      Stock for order 42 already reserved, skipping duplicate

Side by side

Criterion	MassTransit v8 / v9	Wolverine 6	RabbitMQ.Client 7
Setup effort	Low: consumer, definition, `ConfigureEndpoints`	Low: handler class, a few routing rules	High: connection, channels, topology, worker
Learning curve	Medium; large feature set and docs	Medium; conventions and code generation to learn	Low API surface, but you must know AMQP (Advanced Message Queuing Protocol) well
Retries	`UseMessageRetry`, plus scheduled redelivery	`RetryWithCooldown`, `ScheduleRetry`, per-exception rules	Hand-written (TTL retry queue here)
Error path	`_error` queue and `Fault<T>` events	Native dead-letter queue or database storage	Hand-written error queue
Idempotency help	Inbox inside its consumer outbox	Durable inbox, deduplication by envelope id	None
Sagas and workflows	State machines, routing slips	Sagas	None
Testing	`AddMassTransitTestHarness`	Tracked sessions, `InvokeMessageAndWaitAsync`	Your own integration tests
Runtime overhead	Middleware pipeline per message	Generated code per handler	Lowest; only your code
.NET support	v8.5 targets .NET 8, 9, and 10	.NET 9 and 10 (5.x for .NET 8)	.NET Standard 2.0 and .NET 8+
License and cost	v9 commercial subscription; v8 Apache 2.0	MIT, free	Apache 2.0 or MPL 2.0, free
Maintenance	Active (v9); v8 patches still shipping	Very active, frequent releases	Active, official client

How to choose

You run MassTransit sagas or routing slips in production. Price the v9 license first. Rewriting state machines costs more than most subscriptions, and v9 includes the fixes from the v8 codebase.
You use MassTransit only for publish and consume. Wolverine is the shortest move: the handler is smaller than the consumer, and retry rules map almost one to one.
You are still on .NET 8 and cannot upgrade soon. Stay on MassTransit v8 or use Wolverine 5.x; Wolverine 6 will not install.
You have one integration and a team that knows RabbitMQ. Raw RabbitMQ.Client is fine, but budget for the parts this article skipped: recovery logging, metrics, and tests for the retry path.
Your company is small. Massient states that organizations under 1 million US dollars in gross annual revenue may qualify for a full discount on the license (commercial support excluded). Check the current terms before you decide on cost alone.

Switching later

What changes if you stay on MassTransit v8

Pin the major version so tooling does not upgrade you by accident:

<PackageReference Include="MassTransit.RabbitMQ" Version="[8.5.11,9.0)" />

# .github/dependabot.yml (inside the nuget update entry)
ignore:
  - dependency-name: "MassTransit*"
    update-types: ["version-update:semver-major"]

Plan for the end of fixes. When v9 was announced in 2025, the plan was security patches and critical fixes for v8 through the end of 2026. After that, assume no fixes and check the MassTransit support page for the current statement.
Upgrading to v9 later is mostly mechanical. The v9 upgrade notes list TransactionalBus removal, per-bus JSON settings, AddSendEndpointConvention renamed to AddMessageRoute, and changed outbox tables in 9.1. You also add the license through MT_LICENSE, MT_LICENSE_PATH, cfg.SetLicense(...), or cfg.SetLicenseLocation(...).

MassTransit to Wolverine

Move one consumer at a time. Wolverine can read and write MassTransit's envelope format on dedicated endpoints with .UseMassTransitInterop() on ListenToRabbitQueue(...) and ToRabbitExchange(...).
Rename consumers to handlers: Consume(ConsumeContext<T>) becomes Handle(T message, ...dependencies).
Queues that MassTransit declared do not have Wolverine's x-dead-letter-exchange argument, and RabbitMQ refuses a redeclare with different arguments. Use new DeadLetterQueue("name", DeadLetterQueueMode.InteropFriendly) or new queue names.

Raw client to a framework

Your messages are plain JSON with no envelope. MassTransit reads them with e.UseRawJsonDeserializer() on the receive endpoint; Wolverine uses .DefaultIncomingMessage<OrderPlaced>() on the listener.
Drain the custom .retry queue before you delete it, or messages waiting there will dead-letter into a queue nobody reads.

Common pitfalls

Publishing after SaveChangesAsync without an outbox. If the broker is down, the order exists and the event is lost. Use MassTransit's or Wolverine's outbox, or the pattern in the playbook guide on the transactional outbox.
Retrying permanent errors. A missing product will fail on every attempt. Mark it as permanent (Ignore<T>, MoveToErrorQueue, or the permanent check) so it reaches the error queue in seconds, not minutes.
Idempotency keyed on transport ids. MassTransit MessageId and Wolverine envelope ids change when a client publishes twice. Key the dedupe table on the business identity.
Wolverine startup cost and missing handlers. Runtime code generation compiles handlers with Roslyn. For production, pre-generate with dotnet run -- codegen write and set opts.CodeGeneration.TypeLoadMode = TypeLoadMode.Static. If a handler is never called, print opts.DescribeHandlerMatch(typeof(OrderPlacedHandler)).
Forgetting the v9 license on build agents. The key must be present wherever MassTransit runs, which includes integration tests on continuous integration agents.

Modern C# Cheat Sheet: C# 10 to C# 14

Softinbit — Wed, 04 Nov 2026 09:39:52 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series The .NET Field Guide.

Every language feature from .NET 6 to .NET 10, each with a one-line purpose and a before/after snippet.

Part of "The .NET Field Guide". Section: Cheat Sheets.

TL;DR

Every C# feature from C# 10 (.NET 6) through C# 14 (.NET 10) condensed into single-purpose before/after snippets tested on .NET 10 SDK (10.0.300).

Fast lookups for top idioms: file-scoped namespaces, raw strings, required properties, primary constructors, collection expressions, Lock, and field-backed properties.

Clear guidance on target framework defaults and compiler diagnostics (#error version) without fragile LangVersion overrides.

Level: Intermediate · Prerequisites: Working knowledge of C# 9 / .NET 5 or earlier · Reading time: 13 min

Your team just moved Store.Api to .NET 10, and a reviewer comments "use field here" on a property you wrote the C# 9 way. This sheet is for developers who learned C# a few versions ago and want the short version of C# 10 (.NET 6) through C# 14 (.NET 10). Every snippet was compiled with the .NET 10 software development kit (SDK), version 10.0.300; outputs and error messages are real.

At a glance

C#	Ships with	Released	Default for	Headline features
10	.NET 6	November 2021	`net6.0`	global usings, file-scoped namespaces, record structs
11	.NET 7	November 2022	`net7.0`	raw strings, `required`, list patterns, generic math
12	.NET 8	November 2023	`net8.0`	primary constructors, collection expressions
13	.NET 9	November 2024	`net9.0`	`params` collections, `Lock`, partial properties
14	.NET 10	November 2025	`net10.0`	extension members, `field`, `?.=` assignment

The lookups people make most:

I want to...	Write	Since
Drop the namespace indent	`namespace Store.Api.Orders;`	10
Import a namespace once per project	`global using Store.Api.Orders;`	10
Paste JavaScript Object Notation (JSON) or SQL without escaping	`"""..."""` and `$$"""...{{x}}..."""`	11
Force callers to set a property	`public required string Name { get; init; }`	11
Inject dependencies without fields	`class OrderService(AppDbContext db)`	12
Create an array or list	`int[] ids = [1, 2, 3];` and `[.. a, .. b]`	12
Accept many arguments without an array	`params ReadOnlySpan<string> tags`	13
Lock without `new object()`	`private readonly Lock _gate = new();`	13
Validate in a setter, no backing field	`set => field = value.Trim();`	14
Add a property to a type you do not own	`extension(Product p) { public bool InStock => ... }`	14
Assign only when the target is not null	`order?.Status = OrderStatus.Paid;`	14
Get `"List"` from a generic type	`nameof(List<>)`	14

Which version you get (LangVersion)

The compiler picks the default C# version from your target framework (the "Default for" column above). You do not need LangVersion in the project file.

Microsoft's documentation states that using a C# version newer than the default for your target framework is not supported. Upgrade the target framework instead.
Do not set <LangVersion>latest</LangVersion>. Its meaning changes with whatever SDK is installed on each machine.
default ignores the target framework, so it is not the same as leaving LangVersion out.
To see what you are compiling with, put #error version in any file:

error CS8304: Compiler version: '5.6.0-2.26230.102 (caa81fa4...)'. Language version: 14.0.

Using a C# 14 feature when the language version is 13 (for example net9.0 built with the .NET 10 SDK):

error CS9260: Feature 'field keyword' is not available in C# 13.0. Please use language version 14.0 or greater.

C# 10 (.NET 6)

Global usings. Import a namespace once for the whole project.

// Before: repeated at the top of every file
using Store.Api.Orders;

// After: once, in GlobalUsings.cs (or <Using Include="Store.Api.Orders" /> in the .csproj)
global using Store.Api.Orders;

File-scoped namespaces. One less indentation level per file.

// Before
namespace Store.Api.Orders
{
    public sealed class OrderService { }
}

// After
namespace Store.Api.Orders;

public sealed class OrderService { }

Record structs. Value-type records with generated equality, ToString, and with.

// Before: a struct with hand-written Equals, GetHashCode, ==, and ToString
// After
public readonly record struct Money(decimal Amount, string Currency);

var a = new Money(10m, "TRY");
var b = a with { Amount = 12m };
Console.WriteLine(a);                           // Money { Amount = 10, Currency = TRY }
Console.WriteLine(a == new Money(10m, "TRY"));  // True

Extended property patterns. Reach into nested members with a dot.

// Before
if (order is { Lines: { Count: > 0 } }) { }

// After
if (order is { Lines.Count: > 0 }) { }

Constant interpolated strings. Build const strings, for example route templates, with $"".

// Before
public const string Products = Base + "/products";

// After
public const string Base = "/api";
public const string Products = $"{Base}/products";   // "/api/products", usable in [Route(Products)]

Lambda improvements. Lambdas get a natural type, an optional explicit return type, and attributes.

// Before
Func<string, int> parse = s => int.Parse(s);

// After
var parse = (string s) => int.Parse(s);          // inferred as Func<string, int>
var pick = object (bool b) => b ? 1 : "one";     // explicit return type
app.MapGet("/api/health", [AllowAnonymous] () => Results.Ok());   // Microsoft.AspNetCore.Authorization

C# 11 (.NET 7)

Raw string literals. Multi-line text with quotes and braces, no escaping.

// Before
var json = "{ \"id\": " + id + ", \"name\": \"Mouse\" }";

// After: $$ means {{x}} interpolates and a single { is literal
var json = $$"""
    { "id": {{id}}, "name": "Mouse" }
    """;
// { "id": 42, "name": "Mouse" }

Required members. The compiler forces object initializers to set these properties.

public sealed class CreateProductRequest
{
    public required string Name { get; init; }
    public required decimal Price { get; init; }
}

var request = new CreateProductRequest { Name = "Mouse" };
// error CS9035: Required member 'CreateProductRequest.Price' must be set in the object initializer or attribute constructor.

Mark a constructor that sets them all with [SetsRequiredMembers] from System.Diagnostics.CodeAnalysis.

List patterns. Match arrays and lists by shape, with .. for "the rest".

// Before: if (ids.Length == 0) ... else if (ids.Length == 1) ...
// After
static string Describe(int[] ids) => ids switch
{
    [] => "empty",
    [var only] => $"one: {only}",
    [var first, .., var last] => $"{first}..{last}",
};
// Describe([1, 2, 3]) -> "1..3"

Generic math (static abstract interface members). Write one numeric algorithm for every number type.

using System.Numerics;

// Before: Sum(IEnumerable<int>), Sum(IEnumerable<decimal>), ...
// After
static T Sum<T>(IEnumerable<T> values) where T : INumber<T>
{
    T total = T.Zero;
    foreach (var v in values) total += v;
    return total;
}
// Sum([10.5m, 20m]) -> 30.5    Sum([1, 2, 3]) -> 6

Your own interfaces can declare static abstract TSelf Zero { get; } the same way.

UTF-8 string literals. Get bytes at compile time.

// Before
byte[] ok = Encoding.UTF8.GetBytes("OK");

// After
ReadOnlySpan<byte> ok = "OK"u8;   // 2 bytes, no runtime encoding

File-local types. A type visible only inside its own file.

// Before: internal helper visible to the whole assembly
// After
file sealed class SkuFormatter
{
    public static string Format(int id) => $"SKU-{id:D5}";   // SKU-00042
}

scoped. Promise that a span parameter does not escape, so callers can pass stack memory.

public ref struct ReceiptWriter
{
    private Span<char> _dest;
    public int Written;
    public ReceiptWriter(Span<char> dest) { _dest = dest; Written = 0; }

    public void Append(scoped ReadOnlySpan<char> text)
    {
        text.CopyTo(_dest[Written..]);
        Written += text.Length;
    }
}
// Without "scoped", w.Append(stackallocBuffer) fails with error CS8350.

C# 12 (.NET 8)

Primary constructors for classes. Constructor parameters in the class header, in scope everywhere.

// Before
public sealed class PriceCalculator
{
    private readonly decimal _vatRate;
    public PriceCalculator(decimal vatRate) => _vatRate = vatRate;
}

// After
public sealed class PriceCalculator(decimal vatRate)
{
    public decimal WithVat(decimal net) => net * (1 + vatRate);   // 100 -> 120.00
}

Collection expressions. One syntax for arrays, lists, spans, and sets, plus .. spread.

// Before
var ids = new int[] { 1, 2, 3 };
var tags = new List<string> { "new", "sale" };
var none = Array.Empty<Product>();

// After
int[] ids = [1, 2, 3];
List<string> tags = ["new", "sale"];
string[] all = [.. tags, "featured"];   // new, sale, featured
Product[] none = [];

Default lambda parameters. Optional parameters on lambdas.

// Before: a local function or two overloads
// After
var discount = (decimal price, decimal rate = 0.10m) => price * (1 - rate);
discount(100m);          // 90.00
discount(100m, 0.25m);   // 75.00

Alias any type. using aliases for tuples, arrays, and pointer types.

// Before: only named types could be aliased
// After
using LineTotal = (int ProductId, decimal Total);

LineTotal line = (5, 59.90m);
Console.WriteLine(line.Total);   // 59.90

Inline arrays. A fixed-size buffer inside a struct, without unsafe.

using System.Runtime.CompilerServices;

[InlineArray(3)]
public struct LastThreePrices
{
    private decimal _element0;
}

var last = new LastThreePrices();
last[0] = 10m; last[1] = 20m; last[2] = 30m;   // indexable and foreach-able

Experimental attribute. Mark APIs that callers must opt into.

using System.Diagnostics.CodeAnalysis;

[Experimental("STORE001")]
public static class Recommendations
{
    public static string[] For(int userId) => ["Mouse", "Keyboard"];
}
// Calling it from Store.Api.Products without suppression:
// error STORE001: 'Store.Api.Products.Recommendations' is for evaluation purposes only and is
// subject to change or removal in future updates. Suppress this diagnostic to proceed.

Suppress with #pragma warning disable STORE001 or <NoWarn>STORE001</NoWarn>. Also new in C# 12: ref readonly parameters, and interceptors as a preview feature.

C# 13 (.NET 9)

params collections. params works with spans and collection interfaces, not only arrays.

// Before: allocates an array on every call
public static string Tags(params string[] tags) => string.Join("|", tags);

// After
public static string Tags(params ReadOnlySpan<string> tags) => string.Join("|", tags);
public static int CountIds(params IEnumerable<int> ids) => ids.Count();
// Tags("new", "sale") -> "new|sale"

System.Threading.Lock. A dedicated lock type; lock uses its API instead of Monitor.

// Before
private readonly object _gate = new();

// After
private readonly Lock _gate = new();

lock (_gate)   // compiles to _gate.EnterScope()
{
    _reserved += qty;
}

\e escape. The ESCAPE character (U+001B) for terminal colors.

// Before
Console.WriteLine("\u001b[32mPaid\u001b[0m");

// After
Console.WriteLine("\e[32mPaid\e[0m");

Partial properties and indexers. Declare in one part, implement in another (source generators use this).

public partial class ProductView
{
    public partial string Sku { get; set; }   // declaring part
}

public partial class ProductView
{
    private string _sku = "";
    public partial string Sku                 // implementing part
    {
        get => _sku;
        set => _sku = value.ToUpperInvariant();
    }
}

Implicit index access in object initializers. ^ (from the end) works inside initializers.

public sealed class Shelf { public int[] Slots { get; } = new int[5]; }

// Before: front indexes only, { Slots = { [4] = 99 } }
// After
var shelf = new Shelf { Slots = { [^1] = 99, [0] = 1 } };   // 1,0,0,0,99

OverloadResolutionPriority. Library authors steer callers to a better overload without breaking them.

using System.Runtime.CompilerServices;

public static class Logging
{
    public static string Log(string message) => "string overload";

    [OverloadResolutionPriority(1)]
    public static string Log(ReadOnlySpan<char> message) => "span overload";
}
// Logging.Log("hello") -> "span overload"

ref struct interfaces and allows ref struct. Span-holding types can implement interfaces and flow through generics.

public interface ISkuSource { int Count { get; } }

public ref struct SpanSkuSource : ISkuSource
{
    private readonly ReadOnlySpan<string> _skus;
    public SpanSkuSource(ReadOnlySpan<string> skus) => _skus = skus;
    public int Count => _skus.Length;
}

static int CountOf<T>(T source) where T : ISkuSource, allows ref struct => source.Count;

Also in C# 13: ref locals and unsafe blocks inside async methods and iterators (not across await or yield), and smarter method group overload resolution.

C# 14 (.NET 10)

Extension members. Extension blocks add properties, methods, and static members to types you do not own.

// Before: extension methods only
public static bool InStock(this Product p) => p.Stock > 0;

// After
public static class ProductExtensions
{
    extension(Product product)
    {
        public bool InStock => product.Stock > 0;
        public decimal PriceWithVat(decimal rate) => product.Price * (1 + rate);
    }

    extension(Product)
    {
        public static Product Placeholder => new() { Name = "(none)" };
    }
}
// p.InStock -> True    p.PriceWithVat(0.20m) -> 120.00    Product.Placeholder.Name -> (none)

The field keyword. Use the compiler-generated backing field inside an accessor.

// Before
private string _email = "";
public string Email
{
    get => _email;
    set => _email = value.Trim().ToLowerInvariant();
}

// After
public string Email
{
    get;
    set => field = value.Trim().ToLowerInvariant();
} = "";
// "  Ali@Example.COM " -> "ali@example.com"

Null-conditional assignment. ?. and ?[] on the left side of = and compound assignments.

// Before
if (order is not null) order.Status = OrderStatus.Paid;

// After
order?.Status = OrderStatus.Paid;   // right side runs only when order is not null
order?.Total += 10m;
// order?.Total++;  -> error CS1059 (++ and -- are not allowed here)

Implicit span conversions. Arrays convert to spans for extension receivers and generic inference.

public static decimal Total(this ReadOnlySpan<decimal> prices)
{
    decimal sum = 0;
    foreach (var p in prices) sum += p;
    return sum;
}

decimal[] prices = [10m, 20m];
prices.Total();
// C# 13: error CS1929: 'decimal[]' does not contain a definition for 'Total' ...
// C# 14: compiles and returns 30

nameof with unbound generics. No dummy type argument needed.

// Before
nameof(List<int>)        // "List"

// After
nameof(List<>)           // "List"
nameof(Dictionary<,>)    // "Dictionary"

Simple lambda parameters with modifiers. out, ref, in, scoped without spelling out types (params still needs them).

public delegate bool TryParser<T>(string text, out T result);

// Before
TryParser<decimal> p1 = (string text, out decimal result) => decimal.TryParse(text, out result);

// After
TryParser<decimal> p2 = (text, out result) => decimal.TryParse(text, out result);

Partial constructors and partial events. One defining and one implementing declaration, like partial methods.

public partial class Cart
{
    public partial Cart(int id);
    public partial event EventHandler? Changed;
}

public partial class Cart
{
    private EventHandler? _changed;
    public int Id { get; }
    public partial Cart(int id) { Id = id; }
    public partial event EventHandler? Changed
    {
        add => _changed += value;
        remove => _changed -= value;
    }
}

User-defined compound assignment. Overload += and ++ as instance operators that mutate in place.

// Before: static operator + creates a new object on every +=
// After
public sealed class Basket
{
    public decimal Total { get; private set; }
    public int Items { get; private set; }

    public void operator +=(decimal price) { Total += price; Items++; }
    public void operator ++() => Items++;
}

var basket = new Basket();
basket += 50m; basket += 25m; basket++;   // Total 75, Items 3

C# 14 also adds preprocessor directives for file-based apps (dotnet run app.cs).

Gotchas

field is now a keyword inside property accessors. A class with a member named field gets warning CS9258; write @field or this.field for the old member.
Primary constructor parameters are mutable captured state, not readonly fields. Using one both to initialize a field and directly in a method gives warning CS9124 (two copies).
var x = [1, 2]; fails with CS9176 "There is no target type for the collection expression." Give the variable a type.
Casting a Lock to object silently falls back to Monitor locking; the compiler warns with CS9216.
[Experimental] produces an error, not a warning, until the caller suppresses that exact ID.
required is a compile-time check on object initializers, not input validation.
An instance member always wins over an extension member with the same name.
?.= skips the right side entirely when the target is null, including its side effects.

Copy-paste snippets

Solution-wide defaults. Put this next to your .sln; keep global usings in Store.Api.csproj so test projects still build.

<!-- File: Directory.Build.props -->
<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <!-- No LangVersion: net10.0 gives you C# 14 -->
  </PropertyGroup>
</Project>

<!-- File: Store.Api.csproj (inside <Project>) -->
<ItemGroup>
  <Using Include="Store.Api.Orders" />
  <Using Include="Store.Api.Products" />
</ItemGroup>

A request data transfer object (DTO) with required and field validation.

// File: Products/CreateProductRequest.cs
namespace Store.Api.Products;

public sealed class CreateProductRequest
{
    public required string Name
    {
        get;
        init => field = value.Trim();
    }

    public required decimal Price
    {
        get;
        init => field = value >= 0m
            ? value
            : throw new ArgumentOutOfRangeException(nameof(Price), "Price cannot be negative.");
    }

    public int Stock { get; init; }
}

A service with a primary constructor, collection expressions, and patterns.

// File: Orders/OrderPricing.cs
namespace Store.Api.Orders;

public sealed class OrderPricing(TimeProvider clock)
{
    private static readonly HashSet<DayOfWeek> Weekend = [DayOfWeek.Saturday, DayOfWeek.Sunday];

    public decimal ShippingFee(Order order) => order switch
    {
        { Lines.Count: 0 } => 0m,
        { Total: >= 500m } => 0m,
        _ when Weekend.Contains(clock.GetUtcNow().DayOfWeek) => 29.90m,
        _ => 49.90m
    };

    public static int[] ProductIds(Order order) =>
        [.. order.Lines.Select(l => l.ProductId).Distinct()];
}

Register it with builder.Services.AddSingleton(TimeProvider.System); and builder.Services.AddScoped<OrderPricing>();.

An HTML email body with a raw interpolated string.

// File: Infrastructure/Email/OrderEmailTemplates.cs
using System.Globalization;
using System.Net;
using Store.Api.Orders;

namespace Store.Api.Infrastructure.Email;

public static class OrderEmailTemplates
{
    private static readonly CultureInfo Turkish = CultureInfo.GetCultureInfo("tr-TR");

    public static string Confirmation(Order order, string customerName) => $$"""
        <h1>Thank you, {{WebUtility.HtmlEncode(customerName)}}</h1>
        <p>Order #{{order.Id}} is {{order.Status}}.</p>
        <p>Total: {{order.Total.ToString("C", Turkish)}}</p>
        """;
}

Output for order 1001 with a total of 1200 and the name Ayşe <VIP>:

<h1>Thank you, Ayşe &lt;VIP&gt;</h1>
<p>Order #1001 is Paid.</p>
<p>Total: ₺1.200,00</p>

Pass the result to IEmailService.SendAsync(to, subject, htmlBody, ct).

Issuing and Validating JWT Access Tokens in ASP.NET Core

Softinbit — Tue, 03 Nov 2026 07:27:07 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series The .NET Implementation Playbook.

Register users, log them in, and protect endpoints with signed 15-minute access tokens.

Part of "The .NET Implementation Playbook". Section: Authentication and Security.

TL;DR

Issue signed 15-minute access tokens for ASP.NET Core Identity users with JsonWebTokenHandler, the same handler JwtBearer uses to validate them.

Validate strictly: issuer, audience, lifetime, HS256 only, a 30-second clock skew, and a signing key whose length is checked at startup.

Avoid the classic traps: claim mapping that hides sub, AddIdentity in an API, and authentication middleware in the wrong order.

Level: Intermediate · Prerequisites: An ASP.NET Core Web API project, basic EF Core, SQL Server or LocalDB · Reading time: 13 min

Your Angular app and a mobile client both need to call Store.Api, and the ticket says "add login". Browser cookies tied to one domain do not fit both clients, so the API will issue its own JSON Web Tokens (JWT): short-lived, signed strings that the client sends in the Authorization header on every request.

In this guide you store users and password hashes with ASP.NET Core Identity, issue a JWT at login, and validate it on every protected request. The rest of the series builds on the types you add here: AppUser, AppDbContext, JwtOptions, ITokenService, TokenResult, and ICurrentUser.

What you will build

POST /api/auth/register creates a user with a hashed password in SQL Server.
POST /api/auth/login verifies the password, counts failures, locks the account for 15 minutes after five failures, and returns a signed access token.
The token carries sub, email, role, and jti claims and expires after 15 minutes.
Every request with Authorization: Bearer <token> is checked for signature, issuer, audience, and lifetime.
GET /api/auth/me returns the caller's id, email, and roles, and returns 401 without a valid token.

Before you start

.NET 10, the current LTS. The code also compiles on .NET 8 and 9, but both reach end of support on November 10, 2026; Upgrading a Production API from .NET 8 to .NET 10: What Broke covers the move.
An ASP.NET Core Web API project named Store.Api with controllers, builder.Services.AddControllers(), builder.Services.AddProblemDetails(), and implicit usings enabled (the template default).
SQL Server or LocalDB, and the dotnet-ef tool.

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet tool install --global dotnet-ef

These packages ship one major version per .NET release, so keep their major version in line with your target framework (on .NET 8, pass --version with the latest 8.0 patch). JwtBearer brings in Microsoft.IdentityModel.JsonWebTokens and Microsoft.IdentityModel.Tokens, which hold the token classes used below.

How it works

Register. Identity hashes the password and stores the user in the AspNetUsers table.
Login. The API loads the user by email, refuses locked accounts, verifies the hash, and builds a JWT.
The token. A JWT has three Base64Url parts separated by dots: a header ("alg": "HS256"), a payload of claims, and a signature. The signature is an HMAC (Hash-based Message Authentication Code) over header and payload, computed with a secret key that only the API knows.
Later requests. The client sends Authorization: Bearer <token>.
Validation. The JwtBearer handler recomputes the signature with the same key, checks exp and nbf against the clock (plus a small skew), checks that iss matches your issuer and aud matches your audience. Any failure ends in 401 with a WWW-Authenticate header.
Success. The claims become HttpContext.User, [Authorize] passes, and your code reads the user id from sub.

POST /login -> UserManager (lockout, password hash) -> TokenService -> JWT
GET /me + Bearer JWT -> JwtBearer (signature, exp, iss, aud) -> HttpContext.User -> [Authorize] -> controller

A JWT is signed, not encrypted. Anyone holding it can decode the payload and read every claim. The signature only proves that your API issued it and that nobody changed it, so never put secrets or sensitive personal data in claims. Since .NET 8, JwtBearer validates tokens with JsonWebTokenHandler by default instead of the older JwtSecurityTokenHandler, so this guide uses the same handler to create them.

Step 1: Add the AppUser entity

// File: Auth/AppUser.cs
using Microsoft.AspNetCore.Identity;

namespace Store.Api.Auth;

public class AppUser : IdentityUser
{
    // Add your own profile columns here later, for example DisplayName.
}

IdentityUser already has everything login needs: a string Id, UserName, Email, PasswordHash, SecurityStamp, AccessFailedCount, and LockoutEnd. You still create your own subclass on day one, because changing the user type later means touching every UserManager<T> and a migration. Other guides refer to it as Store.Api.Auth.AppUser.

Step 2: Add the Identity DbContext

// File: Data/AppDbContext.cs
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
using Store.Api.Auth;

namespace Store.Api.Data;

public class AppDbContext(DbContextOptions<AppDbContext> options)
    : IdentityDbContext<AppUser>(options)
{
    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);
        builder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
    }
}

IdentityDbContext<AppUser> maps the users, roles, user-role links, claims, logins, and tokens tables.
base.OnModelCreating(builder) must run first. Without it, EF Core fails with The entity type 'IdentityUserLogin<string>' requires a primary key.
ApplyConfigurationsFromAssembly picks up every IEntityTypeConfiguration<T> class in the project, so later guides (refresh tokens, orders) add a configuration file instead of editing this one.

Step 3: Add JwtOptions and the Jwt settings

// File: Auth/JwtOptions.cs
using System.ComponentModel.DataAnnotations;

namespace Store.Api.Auth;

public sealed class JwtOptions
{
    public const string SectionName = "Jwt";

    [Required]
    public string Issuer { get; set; } = string.Empty;

    [Required]
    public string Audience { get; set; } = string.Empty;

    [Required]
    public string Key { get; set; } = string.Empty;

    [Range(1, 60)]
    public int AccessTokenMinutes { get; set; } = 15;
}

Add the connection string and the non-secret JWT settings to appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=StoreDb;Trusted_Connection=True;TrustServerCertificate=True"
  },
  "Jwt": {
    "Issuer": "https://localhost:7001",
    "Audience": "store-api",
    "AccessTokenMinutes": 15
  }
}

The signing key does not go in that file. Store it in user secrets for development:

dotnet user-secrets init
dotnet user-secrets set "Jwt:Key" "$(openssl rand -base64 48)"

On Windows without OpenSSL, generate the value in PowerShell 7 with [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48)) and paste it into the set command.

48 random bytes become a 64-character Base64 string. The API uses the UTF-8 bytes of that string as the HMAC key, so the key is 64 bytes long.
HS256 needs a key of at least 32 bytes (256 bits). Shorter keys fail at token creation with IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'HS256'. Step 7 checks the length at startup so you find out before the first login.
In production, set the key through an environment variable (Jwt__Key) or a secret store. Anyone who has the key can mint valid tokens for any user.

Step 4: Add the token service

// File: Auth/ITokenService.cs
namespace Store.Api.Auth;

public interface ITokenService
{
    TokenResult CreateAccessToken(AppUser user, IEnumerable<string> roles);
}

public sealed record TokenResult(string AccessToken, DateTimeOffset ExpiresAt);

// File: Auth/TokenService.cs
using System.Security.Claims;
using System.Text;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

namespace Store.Api.Auth;

public sealed class TokenService : ITokenService
{
    private readonly JsonWebTokenHandler _handler = new();
    private readonly JwtOptions _options;
    private readonly SigningCredentials _credentials;
    private readonly TimeProvider _timeProvider;

    public TokenService(IOptions<JwtOptions> options, TimeProvider timeProvider)
    {
        _options = options.Value;
        _timeProvider = timeProvider;
        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_options.Key));
        _credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
    }

    public TokenResult CreateAccessToken(AppUser user, IEnumerable<string> roles)
    {
        var now = _timeProvider.GetUtcNow();
        var expiresAt = now.AddMinutes(_options.AccessTokenMinutes);

        var claims = new List<Claim>
        {
            new(JwtRegisteredClaimNames.Sub, user.Id),
            new(JwtRegisteredClaimNames.Email, user.Email ?? string.Empty),
            new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };
        claims.AddRange(roles.Select(role => new Claim("role", role)));

        var descriptor = new SecurityTokenDescriptor
        {
            Issuer = _options.Issuer,
            Audience = _options.Audience,
            Subject = new ClaimsIdentity(claims),
            IssuedAt = now.UtcDateTime,
            NotBefore = now.UtcDateTime,
            Expires = expiresAt.UtcDateTime,
            SigningCredentials = _credentials
        };

        return new TokenResult(_handler.CreateToken(descriptor), expiresAt);
    }
}

JwtRegisteredClaimNames exists in both Microsoft.IdentityModel.JsonWebTokens and System.IdentityModel.Tokens.Jwt. This guide uses only the first, so the two never collide in one file.
sub is the user id, jti is a unique token id you can log or put on a deny list, and every role becomes its own role claim. One role serializes as a string, several as a JSON array.
Expires, IssuedAt, and NotBefore come from TimeProvider, so a test can swap in FakeTimeProvider (package Microsoft.Extensions.TimeProvider.Testing) and check expiry without waiting.
The key and credentials are built once in the constructor. The service holds no per-request state, so it is registered as a singleton.

Step 5: Add ICurrentUser

// File: Auth/ICurrentUser.cs
namespace Store.Api.Auth;

public interface ICurrentUser
{
    string? UserId { get; }
    bool IsAuthenticated { get; }
    bool IsInRole(string role);
}

// File: Auth/HttpCurrentUser.cs
using System.Security.Claims;

namespace Store.Api.Auth;

public sealed class HttpCurrentUser(IHttpContextAccessor accessor) : ICurrentUser
{
    private ClaimsPrincipal? Principal => accessor.HttpContext?.User;

    public string? UserId => Principal?.FindFirst("sub")?.Value;

    public bool IsAuthenticated => Principal?.Identity?.IsAuthenticated ?? false;

    public bool IsInRole(string role) => Principal?.IsInRole(role) ?? false;
}

Controllers can read User directly, but services (order placement, auditing) should not depend on HttpContext. They take ICurrentUser instead, and tests pass a fake. UserId reads the raw sub claim, which only works because Step 7 turns off claim type mapping. Outside a request (a background job), HttpContext is null and every member returns "anonymous".

Step 6: Add the request contracts and AuthController

// File: Auth/AuthContracts.cs
using System.ComponentModel.DataAnnotations;

namespace Store.Api.Auth;

public sealed record RegisterRequest(
    [Required, EmailAddress] string Email,
    [Required] string Password);

public sealed record LoginRequest(
    [Required, EmailAddress] string Email,
    [Required] string Password);

public sealed record MeResponse(string UserId, string? Email, string[] Roles);

// File: Auth/AuthController.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;

namespace Store.Api.Auth;

[ApiController]
[Route("api/auth")]
public sealed class AuthController(
    UserManager<AppUser> userManager,
    ITokenService tokenService,
    ICurrentUser currentUser) : ControllerBase
{
    [HttpPost("register")]
    [AllowAnonymous]
    public async Task<IActionResult> Register(RegisterRequest request)
    {
        var user = new AppUser { UserName = request.Email, Email = request.Email };
        var result = await userManager.CreateAsync(user, request.Password);
        if (!result.Succeeded)
        {
            foreach (var error in result.Errors)
            {
                ModelState.AddModelError(error.Code, error.Description);
            }
            return ValidationProblem(ModelState);
        }

        return StatusCode(StatusCodes.Status201Created, new { id = user.Id, email = user.Email });
    }

    [HttpPost("login")]
    [AllowAnonymous]
    public async Task<IActionResult> Login(LoginRequest request)
    {
        var user = await userManager.FindByEmailAsync(request.Email);
        if (user is null || await userManager.IsLockedOutAsync(user))
        {
            return InvalidCredentials();
        }

        if (!await userManager.CheckPasswordAsync(user, request.Password))
        {
            await userManager.AccessFailedAsync(user);
            return InvalidCredentials();
        }

        await userManager.ResetAccessFailedCountAsync(user);
        var roles = await userManager.GetRolesAsync(user);
        return Ok(tokenService.CreateAccessToken(user, roles));
    }

    [HttpGet("me")]
    [Authorize]
    public IActionResult Me()
    {
        var roles = User.FindAll("role").Select(c => c.Value).ToArray();
        return Ok(new MeResponse(currentUser.UserId!, User.FindFirst("email")?.Value, roles));
    }

    private ObjectResult InvalidCredentials() =>
        Problem(statusCode: StatusCodes.Status401Unauthorized, title: "Invalid email or password.");
}

One error for every failure. Unknown email, locked account, and wrong password all return the same 401, so the login form cannot be used to discover which emails have accounts. The trade-off: a locked-out user sees a generic message. If your product prefers a "try again in 15 minutes" message, return it only after the password check succeeds.
Lockout. AccessFailedAsync increments AccessFailedCount. When it reaches MaxFailedAccessAttempts, Identity sets LockoutEnd and resets the counter. IsLockedOutAsync runs before the password check, so a locked account rejects even the correct password until the lockout ends.
Reset on success. ResetAccessFailedCountAsync stops old failures from adding up across days.
UserName = Email. Identity requires a unique user name. Using the email keeps one identifier.
Me needs no database call. Everything it returns comes from the validated token.
[AllowAnonymous] changes nothing yet, but it keeps these actions open once Role-Based and Policy-Based Authorization in ASP.NET Core adds a fallback policy that requires login everywhere.

Step 7: Register everything in Program.cs

// File: Program.cs (usings at the top, the rest before builder.Build())
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.Tokens;
using Store.Api.Auth;
using Store.Api.Data;

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services
    .AddIdentityCore<AppUser>(options =>
    {
        options.User.RequireUniqueEmail = true;
        options.Password.RequiredLength = 8;
        options.Password.RequireDigit = true;
        options.Password.RequireUppercase = true;
        options.Password.RequireNonAlphanumeric = false;
        options.Lockout.AllowedForNewUsers = true;
        options.Lockout.MaxFailedAccessAttempts = 5;
        options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15);
    })
    .AddRoles<IdentityRole>()
    .AddEntityFrameworkStores<AppDbContext>()
    .AddDefaultTokenProviders();

builder.Services.AddOptions<JwtOptions>()
    .Bind(builder.Configuration.GetSection(JwtOptions.SectionName))
    .ValidateDataAnnotations()
    .Validate(o => Encoding.UTF8.GetByteCount(o.Key) >= 32,
        "Jwt:Key must be at least 32 bytes (256 bits) for HS256.")
    .ValidateOnStart();

builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddSingleton<ITokenService, TokenService>();
builder.Services.AddHttpContextAccessor();
builder.Services.AddScoped<ICurrentUser, HttpCurrentUser>();

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer();

builder.Services
    .AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
    .Configure<IOptions<JwtOptions>>((bearer, jwtOptions) =>
    {
        var jwt = jwtOptions.Value;
        bearer.MapInboundClaims = false;
        bearer.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = jwt.Issuer,
            ValidateAudience = true,
            ValidAudience = jwt.Audience,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwt.Key)),
            ValidAlgorithms = [SecurityAlgorithms.HmacSha256],
            NameClaimType = "sub",
            RoleClaimType = "role",
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

builder.Services.AddAuthorization();

// File: Program.cs (in the pipeline, after builder.Build() and before app.MapControllers())
app.UseAuthentication();
app.UseAuthorization();

AddIdentityCore, not AddIdentity. AddIdentityCore registers UserManager, password hashing, and validators only. AddIdentity also makes the Identity cookie the default authentication scheme, so JwtBearer never looks at the token. On .NET 8 and 9 that shows up as redirects to a login page that does not exist; on .NET 10, [ApiController] endpoints return 401 even for a valid token. AddRoles<IdentityRole> adds RoleManager and role storage, and AddDefaultTokenProviders enables the email and password reset tokens used by later guides.
Options validation. ValidateDataAnnotations enforces [Required] and [Range], the extra Validate call enforces the 32-byte minimum, and ValidateOnStart runs both when the app starts instead of at the first login.
One source of truth. Configure<IOptions<JwtOptions>> feeds the same validated options into JwtBearer, so issuer, audience, and key cannot drift between the code that signs and the code that validates.
MapInboundClaims = false. By default, JwtBearer renames sub to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier and role to a similar long URI. Turning that off keeps claim names exactly as they appear in the token.
NameClaimType and RoleClaimType. With mapping off, you tell the identity which claims mean "name" and "role". Now User.Identity.Name returns the user id and User.IsInRole("Admin") reads role claims.
ValidAlgorithms. Accepts only HS256, so a token that claims another algorithm in its header is rejected.
ClockSkew. Defaults to 5 minutes, which quietly makes a 15-minute token live for 20. Thirty seconds covers normal clock drift between servers.
Order. UseAuthentication() must come before UseAuthorization(). Otherwise User is still anonymous when authorization runs.

Step 8: Create the database

dotnet ef migrations add InitialIdentity
dotnet ef database update

The migration creates AspNetUsers, AspNetRoles, AspNetUserRoles, AspNetUserClaims, AspNetUserLogins, AspNetUserTokens, and AspNetRoleClaims. Applying migrations in production deserves its own process. EF Core Code-First Migrations: From First Migration to Production Deploy covers it.

Try it

Save this as Store.Api.http. Request variables (# @name) work in Visual Studio 2026, Visual Studio 2022 17.12 or later, and the VS Code REST Client extension.

@baseUrl = https://localhost:7001

### Register
POST {{baseUrl}}/api/auth/register
Content-Type: application/json

{ "email": "ada@example.com", "password": "Passw0rd!" }

### Login
# @name login
POST {{baseUrl}}/api/auth/login
Content-Type: application/json

{ "email": "ada@example.com", "password": "Passw0rd!" }

### Who am I (200)
GET {{baseUrl}}/api/auth/me
Authorization: Bearer {{login.response.body.$.accessToken}}

### No token (401)
GET {{baseUrl}}/api/auth/me

### Wrong password (401)
POST {{baseUrl}}/api/auth/login
Content-Type: application/json

{ "email": "ada@example.com", "password": "wrong" }

Expected results:

Register        201 {"id":"12ea3a76-3f24-4179-895c-fd8d624c3397","email":"ada@example.com"}
Login           200 {"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi(shortened)","expiresAt":"2026-10-12T21:05:41.5891408+00:00"}
Who am I        200 {"userId":"12ea3a76-3f24-4179-895c-fd8d624c3397","email":"ada@example.com","roles":[]}
No token        401, empty body, header WWW-Authenticate: Bearer
Wrong password  401 {"type":"https://tools.ietf.org/html/rfc9110#section-15.5.2","title":"Invalid email or password.","status":401,"traceId":"00-d861aa6f..."}

Change one character in the middle of the token and call /api/auth/me again. The response is 401 with WWW-Authenticate: Bearer error="invalid_token", error_description="The signature key was not found", because no key produces that signature. An expired token gives error_description="The token expired at '...'" instead. Send the wrong password five times and then the correct one: you get 401 until the 15-minute lockout ends.

Finally, decode the payload to see that it is readable by anyone:

TOKEN="paste-the-access-token-here"
p=$(echo "$TOKEN" | cut -d '.' -f 2 | tr '_-' '/+')
while [ $(( ${#p} % 4 )) -ne 0 ]; do p="$p="; done
echo "$p" | base64 -d

{"sub":"12ea3a76-3f24-4179-895c-fd8d624c3397","email":"ada@example.com","jti":"991d6580-36e2-425b-85a2-8e8b4b0f4bac","aud":"store-api","iss":"https://localhost:7001","exp":1791839141,"iat":1791838241,"nbf":1791838241}

Production checklist

Load Jwt:Key from an environment variable or a secret store such as Azure Key Vault, and never commit it.
Keep access tokens short and add refresh tokens instead of raising AccessTokenMinutes.
Rate-limit /api/auth/login and /api/auth/register with the built-in rate limiter (AddRateLimiter), which also slows down email probing by response timing.
Serve the API over HTTPS only and enable HTTP Strict Transport Security (app.UseHsts()) outside development.
Plan key rotation: TokenValidationParameters.IssuerSigningKeys accepts several keys, so you can validate old and new tokens during the switch.
Move to an asymmetric algorithm (RS256 or ES256) when other services must validate tokens but must not be able to issue them.
Never log full tokens. Log jti and sub instead.

Common pitfalls

UseAuthorization() before UseAuthentication(). Every protected endpoint returns 401 because the user is still anonymous when authorization runs. Put authentication first.
Leaving claim mapping on. FindFirst("sub") returns null because the claim was renamed to the long nameidentifier URI. Set MapInboundClaims = false and the two claim types.
Calling AddIdentity in an API. The Identity cookie becomes the default scheme. On .NET 8 and 9, unauthenticated calls get a 302 redirect to /Account/Login; on .NET 10, API endpoints return 401 even with a valid bearer token. Use AddIdentityCore.
A short signing key. Login fails with IDX10720 at runtime. The startup validation in Step 7 catches it earlier, and openssl rand -base64 48 avoids it.
Issuer or audience drift. A trailing slash in one place produces 401 with "The issuer ... is invalid". Read both values from the same JwtOptions, as this guide does.
Casting to JwtSecurityToken in JwtBearer events. Since .NET 8, context.SecurityToken is a JsonWebToken, so the cast returns null. Cast to JsonWebToken instead.

Related guides

Refresh Tokens in ASP.NET Core: Rotation, Reuse Detection, and Logout
Role-Based and Policy-Based Authorization in ASP.NET Core
Adding a JWT Authorize Button to Swagger UI
Password Reset by Email with ASP.NET Core Identity

Originally published at www.softinbit.com. Part of The .NET Implementation Playbook.

Upgrading a Production API from .NET 8 to .NET 10: What Broke

Softinbit — Mon, 02 Nov 2026 09:13:11 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series The .NET Field Guide.

How one team moved Store.Api to .NET 10 before .NET 8 support ended, and the exact fix for every break they hit on the way.

Part of "The .NET Field Guide". Section: Case Studies.

TL;DR

.NET 8 and .NET 9 both lose support on November 10, 2026. This case study moves a production API straight to .NET 10 LTS and walks through every break the team hit.

Most breaks were loud build errors (obsolete IPNetwork, Swashbuckle 10, EF Core 10 ExecuteUpdate). Two were silent: a missing exception log that muted an alert, and 401s where tests expected cookie redirects.

You get before/after code for each fix, a temporary net8.0/net10.0 CI matrix, and a checklist to run on your own project.

Level: Advanced · Prerequisites: ASP.NET Core Web API and EF Core experience, basic Docker and CI · Reading time: 12 min

This is an illustrative case study. It combines situations that are common in production .NET systems. The company, people, and details are invented, and no numbers are presented as real measurements unless they come from the demo code in this article.

The ticket looked harmless: "Move Store.Api to .NET 10." Elif, the team lead, attached one line from Microsoft's support policy page. .NET 8 and .NET 9 both reach end of support on November 10, 2026. After that date there are no more security patches, and the security team would start flagging the API in every audit.

Kerem opened the first pull request on a Monday. He changed net8.0 to net10.0, pushed, and watched CI turn red. By Thursday the build was green again, the staging deploy looked healthy, and the error-rate alert had gone completely quiet. That silence turned out to be the most dangerous break of all.

The situation

Store.Api is the backend for a mid-size Turkish e-commerce company: an ASP.NET Core Web API with controllers, Entity Framework Core (EF Core) on SQL Server, and JSON Web Tokens (JWT) for the storefront. A small back office reports area uses a separate cookie scheme named BackOffice. The API runs in Docker behind a load balancer, so it relies on forwarded headers. Swagger UI comes from Swashbuckle 6 with a JWT security definition and one operation filter. CI builds with TreatWarningsAsErrors.

The support dates, from the official .NET support policy page:

Version	Type	End of support
.NET 8	LTS	November 10, 2026
.NET 9	STS	November 10, 2026
.NET 10	LTS	November 14, 2028

Skipping .NET 9 was an easy call. The plan had five mechanical steps before any code changes.

Pin the SDK in global.json at the repository root:

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  }
}

Change the target framework in one place, Directory.Build.props:

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

List what is outdated, then align every Microsoft.* package on the same major version:

dotnet list package --outdated
# .NET 10 SDK also accepts the noun-first form:
dotnet package list --outdated --format json > outdated.json

Keep the versions in Directory.Packages.props so no project can drift:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.12" />
    <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.12" />
    <PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.12" />
    <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.1.4" />
  </ItemGroup>
</Project>

Finally, change the container base image tags from 8.0-bookworm-slim to the .NET 10 images. That step broke too.

Symptoms

The breaks arrived in three waves.

At build time:

error ASPDEPR005: 'ForwardedHeadersOptions.KnownNetworks' is obsolete in Program.cs.
error NU1510 on a direct System.Text.Json package reference nobody remembered adding.
NU1903 vulnerability warnings, promoted to errors, for a package the team never referenced directly.
Every Swashbuckle file failed with error CS0234: The type or namespace name 'Models' does not exist in the namespace 'Microsoft.OpenApi'.
The nightly job that cancels stale orders no longer compiled at its ExecuteUpdateAsync call.

At image build time:

docker build failed because the image tag mcr.microsoft.com/dotnet/aspnet:10.0-bookworm-slim does not exist.

On staging:

An integration test that expected 302 Found for an anonymous back office request got 401 Unauthorized.
The "5xx errors with exceptions" alert went silent, while the dashboard still showed 500 responses.
Database CPU rose briefly right after the deploy, then settled.

Investigation

The team grouped build errors by code first, so they could fix one category at a time:

dotnet build -c Release 2>&1 | grep -oE "(error|warning) [A-Z]+[0-9]+" | sort | uniq -c

For the vulnerability warnings, they listed vulnerable transitive packages and asked NuGet which top-level package pulled each one in:

(dotnet package list --vulnerable --include-transitive --format json | ConvertFrom-Json).projects.frameworks.transitivePackages.id |
  Sort-Object -Unique |
  ForEach-Object { dotnet nuget why src/Store.Api/Store.Api.csproj $_ }

The silent alert took longer. The alert query counted log events from one category, Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware. On .NET 8, every exception that reached UseExceptionHandler produced this line, even when Store.Api's IExceptionHandler turned it into a ProblemDetails response:

fail: Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware[1]
      An unhandled exception has occurred while executing the request.
      System.InvalidOperationException: Pricing service returned null

On .NET 10 the 500 response was identical, but that log line never appeared. The handler returned true, and that now means "handled, record nothing".

The 401 was reproducible from a terminal:

curl -i https://localhost:7001/api/admin/reports/daily-sales

HTTP/1.1 401 Unauthorized
Location: https://localhost:7001/admin/login?ReturnUrl=%2Fapi%2Fadmin%2Freports%2Fdaily-sales

The Location header was still there. Only the status code had changed.

For the database CPU bump, the team compared the SQL that EF Core logged on both versions. EF Core 10 names parameters after the variable (@status instead of @__status_0) and translates ids.Contains(o.Id) into IN (@ids1, @ids2, @ids3) instead of an OPENJSON parameter. New SQL text means new cached plans, so every query compiled once after the deploy.

Root cause

Every symptom mapped to a documented breaking change in .NET 10 or in a package upgraded with it:

Symptom	Breaking change	Type
ASPDEPR005	`IPNetwork` and `ForwardedHeadersOptions.KnownNetworks` are obsolete	Source incompatible
Silent alert	Exception diagnostics suppressed when `TryHandleAsync` returns true	Behavioral
401 instead of 302	Cookie login redirects disabled for known API endpoints	Behavioral
Swashbuckle errors	Swashbuckle 10 moved to Microsoft.OpenApi 2.x (namespace and model changes)	Source incompatible
`ExecuteUpdateAsync` error	EF Core 10 setters are a plain lambda, not an expression tree	Source incompatible
SQL text and plans	Parameterized collections use multiple parameters; parameter names simplified	Behavioral
NU1510	NuGet raises NU1510 for direct references pruned by the framework	Source incompatible
NU1903	`dotnet restore` audits transitive packages for net10.0 projects	Behavioral
Missing image tag	Default .NET 10 images use Ubuntu, and no Debian images ship	Behavioral

Two more changes did not break anything but needed attention. dotnet new sln now creates an .slnx file, and the EF Core tools require --framework on multi-targeted projects.

The fix

Forwarded headers

Before (.NET 8):

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownNetworks.Add(new Microsoft.AspNetCore.HttpOverrides.IPNetwork(IPAddress.Parse("10.20.0.0"), 16));
});

After (.NET 10), using System.Net.IPNetwork:

// Program.cs, before builder.Build(). Needs: using Microsoft.AspNetCore.HttpOverrides;
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownIPNetworks.Add(System.Net.IPNetwork.Parse("10.20.0.0/16"));
});

The fully qualified name avoids a clash with the obsolete Microsoft.AspNetCore.HttpOverrides.IPNetwork.

Exception logging

The team decided the handler should own its logging, so the alert no longer depends on middleware internals:

// File: Infrastructure/GlobalExceptionHandler.cs
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

namespace Store.Api.Infrastructure;

public sealed class GlobalExceptionHandler(
    IProblemDetailsService problemDetails,
    ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        // .NET 10 no longer logs exceptions that a handler reports as handled.
        logger.LogError(exception, "Unhandled exception for {Method} {Path}",
            httpContext.Request.Method, httpContext.Request.Path);

        httpContext.Response.StatusCode = StatusCodes.Status500InternalServerError;
        return await problemDetails.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            Exception = exception,
            ProblemDetails = new ProblemDetails
            {
                Status = StatusCodes.Status500InternalServerError,
                Title = "An unexpected error occurred."
            }
        });
    }
}

They updated the alert to the new category, Store.Api.Infrastructure.GlobalExceptionHandler. A team that wants the old behavior instead, including the error.type tag on the http.server.request.duration metric, can opt out of suppression:

// Program.cs, in the pipeline after builder.Build()
app.UseExceptionHandler(new ExceptionHandlerOptions
{
    SuppressDiagnosticsCallback = _ => false
});

Cookie redirects

For [ApiController] endpoints, 401 and 403 are the right answers, so the team fixed the test, not the code:

// File: tests/Store.Api.Tests/BackOfficeAuthTests.cs
using System.Net;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;

namespace Store.Api.Tests;

public sealed class BackOfficeAuthTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    [Fact]
    public async Task Anonymous_report_request_returns_401_with_login_location()
    {
        var client = factory.CreateClient(new WebApplicationFactoryClientOptions { AllowAutoRedirect = false });

        var response = await client.GetAsync("/api/admin/reports/daily-sales");

        Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
        Assert.StartsWith("/admin/login", response.Headers.Location?.AbsolutePath);
    }
}

The test project references Microsoft.AspNetCore.Mvc.Testing and xUnit, and Program must be visible to it (on .NET 10 a source generator makes it public; on .NET 8 add public partial class Program; at the end of Program.cs). One endpoint really was opened from links in emails, a CSV download, so it opts back in to redirects:

[HttpGet("daily-sales.csv")]
[AllowCookieRedirect] // Microsoft.AspNetCore.Http, new in .NET 10
public IActionResult DailySalesCsv() =>
    File("date,total\n"u8.ToArray(), "text/csv", "daily-sales.csv");

Swashbuckle 10 and Microsoft.OpenApi 2.x

The Models namespace is gone, Type is a JsonSchemaType flags enum, and security requirements reference schemes through the document. Before (Swashbuckle 6):

using Microsoft.OpenApi.Models;

options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
        },
        Array.Empty<string>()
    }
});

After (Swashbuckle 10):

// Program.cs, before builder.Build(). Needs: using Microsoft.OpenApi;
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Store.Api", Version = "v1" });
    options.OperationFilter<Store.Api.OpenApi.CorrelationIdHeaderFilter>();
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Description = "Paste the access token only."
    });
    options.AddSecurityRequirement(document => new OpenApiSecurityRequirement
    {
        [new OpenApiSecuritySchemeReference("Bearer", document)] = []
    });
});

// File: OpenApi/CorrelationIdHeaderFilter.cs
using Microsoft.OpenApi;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace Store.Api.OpenApi;

public sealed class CorrelationIdHeaderFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        operation.Parameters ??= [];
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "X-Correlation-Id",
            In = ParameterLocation.Header,
            Required = false,
            Schema = new OpenApiSchema { Type = JsonSchemaType.String, Format = "uuid" }
        });
    }
}

The old filter set Type = "string", which no longer compiles. Swashbuckle 10 still writes OpenAPI 3.0 unless a project opts in to 3.1.

EF Core 10 bulk updates

The stale-order job built its setters as a reusable expression. Before (EF Core 8):

private static Expression<Func<SetPropertyCalls<Order>, SetPropertyCalls<Order>>> CancelSetters() =>
    s => s.SetProperty(o => o.Status, OrderStatus.Cancelled);

await db.Orders
    .Where(o => o.Status == OrderStatus.Pending && o.CreatedAtUtc < cutoffUtc)
    .ExecuteUpdateAsync(CancelSetters(), ct);

EF Core 10 takes an Action<UpdateSettersBuilder<Order>>, so conditional setters become ordinary if statements. Store.Api's real Order has a CancelReason column beyond the minimal shape:

// File: Orders/StaleOrderCanceller.cs
using Microsoft.EntityFrameworkCore;
using Store.Api.Data;

namespace Store.Api.Orders;

public sealed class StaleOrderCanceller(AppDbContext db, TimeProvider clock)
{
    public Task<int> CancelAsync(TimeSpan maxAge, string? reason, CancellationToken ct)
    {
        var cutoffUtc = clock.GetUtcNow().UtcDateTime - maxAge;

        return db.Orders
            .Where(o => o.Status == OrderStatus.Pending && o.CreatedAtUtc < cutoffUtc)
            .ExecuteUpdateAsync(s =>
            {
                s.SetProperty(o => o.Status, OrderStatus.Cancelled);
                if (reason is not null)
                {
                    s.SetProperty(o => o.CancelReason, reason);
                }
            }, ct);
    }
}

Inline chained lambdas such as s => s.SetProperty(...).SetProperty(...) keep compiling. Only stored expression trees break.

For the new collection translation, the team kept the default and watched Query Store. If one query regresses, change that query only:

var orders = await db.Orders
    .Where(o => EF.Parameter(orderIds).Contains(o.Id)) // single JSON parameter, the EF Core 8 and 9 shape
    .ToListAsync(ct);

The global switch is UseSqlServer(connectionString, o => o.UseParameterizedCollectionMode(ParameterTranslationMode.Parameter)).

NuGet warnings

They deleted the System.Text.Json reference (the framework provides it), and upgraded the top-level package that dotnet nuget why named. To keep audit warnings visible without letting a new advisory block an urgent hotfix, they added this to Directory.Build.props:

<PropertyGroup>
  <WarningsNotAsErrors>NU1901;NU1902;NU1903;NU1904;$(WarningsNotAsErrors)</WarningsNotAsErrors>
</PropertyGroup>

A nightly job still fails on any audit warning, so nobody can ignore them for long.

Solution file and Dockerfile

dotnet sln Store.sln migrate        # writes Store.slnx; update CI paths afterwards
dotnet new sln --format sln         # only if a tool in your pipeline cannot read .slnx yet

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish src/Store.Api/Store.Api.csproj -c Release -o /app/publish

# 10.0 is Ubuntu 24.04 "Noble"; there is no Debian variant for .NET 10
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
COPY --from=build /app/publish .
USER $APP_UID
ENTRYPOINT ["dotnet", "Store.Api.dll"]

Port 8080 and the non-root app user are the same as on .NET 8. Re-check any apt-get install lines, because package names can differ between Debian and Ubuntu.

A CI matrix for the transition

For two weeks the team built both frameworks, so a hotfix could still ship on .NET 8. They temporarily replaced <TargetFramework> with <TargetFrameworks>net8.0;net10.0</TargetFrameworks> and made versions conditional:

<ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
  <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.31" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
  <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.12" />
</ItemGroup>

Code that differs goes behind #if NET10_0_OR_GREATER. The workflow runs each framework as its own job:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        tfm: [net8.0, net10.0]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: |
            8.0.x
            10.0.x
      - run: dotnet test Store.slnx -c Release -f ${{ matrix.tfm }}

While multi-targeting, every EF Core tools command needs the framework: dotnet ef migrations add AddCancelReason --framework net10.0.

Results

Store.Api went to production on .NET 10 three weeks before the support deadline. The rollout itself was uneventful because every break had already surfaced in CI or staging. The error alert fired again in staging within minutes of a deliberately broken request, and the database CPU bump after deploy matched the one-time plan recompilation the EF Core documentation warns about. The team removed the net8.0 target, the conditional package versions, and the #if blocks in a follow-up pull request.

What the team would do differently

Read the breaking change lists first. Every surprise was documented. One hour with the ASP.NET Core, EF Core, SDK, and containers lists would have turned them into planned tasks.
Upgrade cross-framework packages before the framework. Swashbuckle 10 also supports net8.0. Doing that migration on .NET 8 would have kept the framework pull request small.
Test the alerts, not just the API. A green test suite said nothing about the log line an alert depended on.
Treat behavioral changes as release notes for operations. Status codes, log categories, and SQL text are contracts with other teams.

Checklist for your project

[ ] Confirm the support dates for every runtime you deploy on the official .NET support policy page.
[ ] Add global.json with the .NET 10 SDK and a rollForward policy.
[ ] Move TargetFramework and package versions to Directory.Build.props and Directory.Packages.props.
[ ] Run dotnet list package --outdated and align all Microsoft.* packages on 10.0.x.
[ ] Search for KnownNetworks, WithOpenApi, WebHostBuilder, and Microsoft.OpenApi.Models.
[ ] Search for stored SetPropertyCalls expressions used with ExecuteUpdate.
[ ] Check every IExceptionHandler: does it log, and does any alert depend on middleware logs?
[ ] Check tests and clients that expect cookie redirects from API endpoints.
[ ] Run dotnet package list --vulnerable --include-transitive and decide how NU190x warnings should fail builds.
[ ] Replace Debian image tags and re-test apt-get lines on Ubuntu.
[ ] Decide between .sln and .slnx before someone runs dotnet new sln.
[ ] Watch database CPU and Query Store for a day after the first deploy.

Setting Up a .NET Developer Machine That Just Works

Softinbit — Thu, 29 Oct 2026 19:45:32 +0000

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series Zero to Full-Stack .NET.

Install the SDK, a database, Git, and Node once, pin them per repository, and stop losing your first week to "it works on my machine".

Part 1 of the "Zero to Full-Stack .NET" series. Section: Getting Started.

TL;DR

Install the .NET 10 SDK and pin each repository's SDK with global.json, so a teammate's preview install never changes your build.

Run a throwaway SQL Server in Docker or LocalDB, and trust the local HTTPS certificate once with dotnet dev-certs https --trust.

Finish with a console app, a Web API, .http smoke tests, and a dotnet CLI cheat sheet you will use every day.

Level: Beginner · Prerequisites: A Windows, macOS, or Linux machine where you can install software · Reading time: 10 min

It is your first Monday. You clone the project, open it, and press Build. The output says the project targets a .NET version you do not have. You install something, try again, and now the app starts but crashes because it cannot reach SQL Server. You fix that, open the browser, and get a red "Your connection is not private" warning on localhost.

None of this is a real bug. It is a machine that was never set up. The team has been working on their laptops for years and nobody remembers which tools they installed, so the onboarding document is three lines long and two of them are wrong.

This article is the setup I wish someone had handed me. It goes in the order you will hit the problems, and every step ends with a command you can run to prove it worked.

What you will be able to do after this

Install the current .NET SDK and pin the version a repository uses with global.json
Run SQL Server locally in Docker or as LocalDB and connect to it from a query tool
Trust the local HTTPS certificate so https://localhost stops warning
Create, run, and test a console app and a Web API from the command line
Use a dotnet CLI cheat sheet instead of clicking through menus

Installing the SDK and pinning it per repository

Download the SDK (not just the runtime) for the current LTS release from the .NET download page on dot.net. LTS means long-term support: it is the version most teams target because it receives fixes for three years. .NET 8 and .NET 10 are both LTS releases; pick the one your team uses, or .NET 10 if you are starting fresh (.NET 8 support ends in November 2026).

Check what you have:

dotnet --list-sdks
# 8.0.xxx [C:\Program Files\dotnet\sdk]
# 10.0.xxx [C:\Program Files\dotnet\sdk]
dotnet --version
# prints the SDK that will be used in the current folder

Having several SDKs installed is normal. The surprise is which one dotnet build picks: without any configuration, it uses the newest one on the machine. That is fine until a teammate installs a preview and a build starts behaving differently. The fix is a global.json at the root of the repository:

{
  "sdk": {
    "version": "8.0.100",
    "rollForward": "latestFeature"
  }
}

rollForward: latestFeature means "use 8.0.100 or any newer 8.0.x feature band, but never jump to 9 or 10". You can generate the file instead of typing it:

dotnet new globaljson --sdk-version 8.0.100 --roll-forward latestFeature

Run dotnet --version inside the repo afterwards. If it prints an error saying the requested SDK was not found, you now know exactly what to install.

Choosing an editor

Editor	Pick it when
Visual Studio Community (2026 for .NET 10; 2022 supports up to .NET 9)	You are on Windows, you want the strongest debugger, designers for Windows Forms, and SQL Server tooling built in. Free for individuals, open source, and small teams.
VS Code with the C# Dev Kit extension	You are on macOS or Linux, you also write Angular or Node, or you want a lighter editor. Install "C# Dev Kit"; it pulls in the C# extension and adds a solution explorer and a test runner.

Both are fine. Many teams use Visual Studio for the API and VS Code for the frontend folder of the same repository. When you install Visual Studio, select the "ASP.NET and web development" workload and, if you will touch desktop tools, ".NET desktop development".

SQL Server for development

You need a SQL Server you can break without consequences. There are two good options.

Docker works on every OS and is the easiest to reset. Install Docker Desktop (on Windows, with the WSL 2 backend), then:

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=Dev_Passw0rd" -p 1433:1433 --name sqldev -d mcr.microsoft.com/mssql/server:2022-latest
# check it stayed up
docker ps
# if it is missing, read why
docker logs sqldev

The password for the sa (system administrator) account must meet SQL Server's complexity rules: at least eight characters, using three of the four groups uppercase, lowercase, digits, and symbols. If it does not, the container exits within seconds and docker ps shows nothing. docker logs tells you.

On Windows without Docker, install SQL Server Express, or use LocalDB, which comes with SQL Server Express and as an optional Visual Studio component. LocalDB is a tiny on-demand instance that starts when you connect:

sqllocaldb info
# MSSQLLocalDB
sqllocaldb start MSSQLLocalDB

Connection strings for the two setups:

Docker:  Server=localhost,1433;Database=Store;User Id=sa;Password=Dev_Passw0rd;TrustServerCertificate=True
LocalDB: Server=(localdb)\MSSQLLocalDB;Database=Store;Trusted_Connection=True

TrustServerCertificate=True is needed for the container because recent SqlClient versions encrypt by default and the container's certificate is self-signed.

To look at tables and run queries, install SQL Server Management Studio (SSMS, Windows only) or, on any OS, VS Code with the MSSQL extension. Azure Data Studio was the older cross-platform option; Microsoft has retired it, so prefer the VS Code extension for new installs. Connect with the values above and run SELECT @@VERSION to confirm.

Git and a GitHub account

Install Git from git-scm.com (on Windows, keep the default "Git from the command line" option). Then tell Git who you are, because every commit is stamped with it:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git --version

Create a GitHub account if you do not have one and set up authentication. The simplest path is the GitHub CLI: gh auth login walks you through a browser login and configures Git to use it. Your team may use Azure DevOps or GitLab instead; the Git commands are identical.

Node.js for the frontend you will write later

Angular, and most frontend tooling, run on Node.js. Do not install Node from the plain installer; use a version manager so you can switch when a project needs a different version. On Windows that is nvm-windows (the nvm-windows project by coreybutler on GitHub):

nvm install lts
nvm use lts
node --version
npm --version

On macOS or Linux use nvm from the nvm-sh project; there the commands are nvm install --lts and nvm use --lts. You do not need Angular today. When you do, npm install -g @angular/cli is one line.

Trusting the HTTPS development certificate

When you run a Web API, Kestrel (the built-in web server) serves https://localhost:xxxx with a self-signed certificate. Browsers reject it until you tell the operating system to trust it:

dotnet dev-certs https --trust

Windows and macOS show a confirmation dialog. On Linux, trust stores differ by distribution and browser, so depending on your SDK version the command may only print instructions; follow them. If something is broken, dotnet dev-certs https --clean followed by the trust command again fixes almost every case.

Your first console app

dotnet new console -n Store.Tools
cd Store.Tools
dotnet run

Open Program.cs. The template uses top-level statements: there is no class Program or Main, just code. Replace the contents with:

var customers = new[] { "Ayşe", "Mehmet", "Zeynep" };

foreach (var name in customers)
{
    Console.WriteLine($"Merhaba, {name}");
}

dotnet run prints three greetings. If it does, the SDK, the compiler, and your terminal all work.

Your first Web API

dotnet new webapi -n Store.Api
cd Store.Api
dotnet run --launch-profile https

In .NET 8 and later this template creates a minimal API: endpoints are defined directly in Program.cs with app.MapGet(...). If your team uses controllers, add --use-controllers to the new command. .NET 9 replaced the Swagger UI package with built-in OpenAPI document generation, so do not be surprised when a newer template has no /swagger page.

Plain dotnet run uses the first profile in Properties/launchSettings.json, which in the template is http, so you would only get http://localhost:5xxx. With --launch-profile https the console prints both URLs, typically https://localhost:7xxx and http://localhost:5xxx. Add a small endpoint below the existing ones (above app.Run()):

app.MapGet("/products", () => new[]
{
    new { Id = 1, Name = "Klavye", Price = 1299.90m },
    new { Id = 2, Name = "Mouse", Price = 449.50m }
});

Then test it without a browser.

Testing HTTP requests from your editor

Visual Studio and VS Code (with the REST Client extension) both understand .http files, and the .NET 8 template already creates Store.Api.http next to the project. Replace its contents with this, using the HTTPS port dotnet run --launch-profile https printed:

@baseUrl = https://localhost:7001

GET {{baseUrl}}/products
Accept: application/json

###

GET {{baseUrl}}/weatherforecast

Click "Send Request" above a request and the response opens beside it. The file is plain text, so it goes into Git and the whole team shares the same smoke tests. Postman does the same job with a richer UI if you prefer it; export the collection into the repository so it is not trapped in one person's account.

The dotnet CLI cheat sheet

dotnet new list                                  # see available templates
dotnet new sln -n Store                          # create a solution
dotnet sln add Store.Api/Store.Api.csproj        # add a project to it
dotnet restore                                   # download NuGet packages
dotnet build                                     # compile
dotnet run --project Store.Api                   # run a project from the solution folder
dotnet watch --project Store.Api                 # rebuild and restart on every save
dotnet test                                      # run all tests in the solution
dotnet add Store.Api package Serilog.AspNetCore  # add a NuGet package to a project
dotnet tool install -g dotnet-ef                 # install a global tool
dotnet format                                    # apply code style from .editorconfig

Commands run against the project in the current folder unless you pass --project. Keeping a terminal open next to the editor is faster than the menus once you know these.

The tools and what each one is for

Tool	Purpose
.NET SDK	Compiler, runtime, and the `dotnet` CLI
Visual Studio or VS Code with C# Dev Kit	Editing and debugging
Docker Desktop with the SQL Server image, or LocalDB	A throwaway database
SSMS or VS Code with the MSSQL extension	Browsing tables and running T-SQL
Git and the GitHub CLI	Version control and pull requests
nvm-windows and Node.js LTS	Frontend tooling and the Angular CLI
`.http` files or Postman	Calling your API by hand
`dotnet-ef` global tool	EF Core migrations from the command line

Common mistakes

Several SDKs and no global.json. The build silently picks the newest SDK and behaves differently on each machine. Add global.json and commit it.
Cloning into a OneDrive, Dropbox, or Google Drive folder. The sync client locks files in bin and obj mid-build and you get random "file in use" errors. Clone to C:\src or ~/src.
Running Visual Studio as administrator out of habit. Files and certificates created under admin become unreadable from a normal terminal. Run it as your own user; nothing in a normal web project needs elevation.
Committing bin and obj. They are build output, change on every build, and cause merge conflicts. Run dotnet new gitignore in the repository root before the first commit.
Skipping dotnet dev-certs https --trust. Every browser warning and every HttpClient call to your own API fails with a certificate error. One command fixes it.
Port 1433 already taken. A previously installed SQL Server Express is listening, so the Docker container cannot bind. Either stop the Windows service or map the container to another port with -p 14333:1433 and use localhost,14333 in the connection string.
An sa password that fails the complexity rules. The container starts, fails validation, and exits. docker logs sqldev shows the message; pick a longer password with mixed character types.

Checklist

dotnet --list-sdks shows the SDK the team targets
global.json exists in the repository root and dotnet --version matches it
SQL Server answers SELECT @@VERSION from SSMS or VS Code
dotnet dev-certs https --trust ran without errors
git config --global user.name and user.email are set
node --version prints an LTS version installed through nvm
dotnet run --launch-profile https in a fresh webapi project serves /weatherforecast over HTTPS
.gitignore from dotnet new gitignore is committed before bin and obj ever are

What's next

With a machine that builds and a database that answers, the next article, "Thinking Like a Programmer: Turning a Vague Request Into Working Code", takes a one-sentence request from a product owner and turns it into a small, tested C# program. After that, "Git for Daily Work: Branches, Pull Requests, and Fixing Mistakes" covers the version control habits that keep a team from overwriting each other.

Originally published at www.softinbit.com. Part of Zero to Full-Stack .NET.

DEV Community: Softinbit

50 Free Developer Tools That Run in Your Browser, Built for .NET Work

What "runs locally" means

Built for .NET work

.NET Stack Trace Cleaner

SQL Server Execution Plan Viewer

Serilog / CLEF Log Viewer

appsettings.json ⇄ Environment Variables

curl to C# HttpClient

JSON to C# Classes

JWT Decoder & Verifier

Connection String Builder & Parser

The everyday tools

Text Compare

Regex Tester

And the rest

Small things that save time

What's next

Thinking Like a Programmer: Turning a Vague Request Into Working Code

What you will be able to do after this

Ask before you type

Write the steps in plain language

Turn each step into a small function

Handle the edge cases the request did not mention

Test with tiny data, then iterate

Reading an error without panicking

Using the debugger instead of Console.WriteLine

Searching for an error the right way

Who you work with

Common mistakes

Checklist

What's next

MassTransit vs Wolverine vs Raw RabbitMQ.Client After the MassTransit License Change

The short answer

What is being compared

The same task in each option

Shared code used by all three options

MassTransit v8

Wolverine

Raw RabbitMQ.Client 7

Side by side

How to choose

Switching later

What changes if you stay on MassTransit v8

MassTransit to Wolverine

Raw client to a framework

Common pitfalls

Related reading

Modern C# Cheat Sheet: C# 10 to C# 14

At a glance

Which version you get (LangVersion)

C# 10 (.NET 6)

C# 11 (.NET 7)

C# 12 (.NET 8)

C# 13 (.NET 9)

C# 14 (.NET 10)

Gotchas

Copy-paste snippets

Related reading

Issuing and Validating JWT Access Tokens in ASP.NET Core

What you will build

Before you start

How it works

Step 1: Add the AppUser entity

Step 2: Add the Identity DbContext

Step 3: Add JwtOptions and the Jwt settings

Step 4: Add the token service

Step 5: Add ICurrentUser

Step 6: Add the request contracts and AuthController

Step 7: Register everything in Program.cs

Step 8: Create the database

Try it

Production checklist

Common pitfalls

Related guides

Upgrading a Production API from .NET 8 to .NET 10: What Broke

The situation

Symptoms

Investigation

Root cause