Cloud-Native .NET

Modern .NET, GitHub and Azure for enterprise apps. A self-study course for senior .NET developers who built their career on .NET Framework, IIS, Remote Desktop and log files, and now want the modern stack: .NET 10, Aspire, GitHub Actions, Azure Container Apps, OpenTelemetry and the reliability habits that come with them.

📅 Written in October 2026 for .NET 10 (LTS), C# 14, Aspire 13 and the Azure services of that time. Facts marked 🔧 change often; check the linked docs.

What "cloud-native .NET" means here

You already know how to build good software. What changed is where it runs and how you know it works.

How the guide works

You join Ledgerly, a small fintech building a portfolio tracker, as a senior .NET developer. Each chapter opens with a problem the team hits, then explains the concepts, shows real code from a working sample, and ends with traps, copy-ready helpers and an optional exercise.

The sample

The repository contains Ledgerly, a runnable .NET 10 system the chapters quote line by line:

Browse it on GitHub.

Tools you need

The whole course can be read without an Azure subscription. Everything up to the deploy runs on your laptop.

Contents

Part 1 · Foundations

1. From legacy to cloud-native: the mental model, the Ledgerly architecture and the course map
2. Modern .NET in one sitting: what changed from .NET Framework 4.8 to .NET 10 and C# 14
3. A solution set up like a pro: central package management, analyzers, warnings as errors, one-command builds

Part 2 · Build, ship, run

4. Designing the API: minimal APIs, validation, ProblemDetails, OpenAPI, CORS, rate limiting
5. Data: EF Core and Azure SQL: EF Core 10, migrations as a deploy step, concurrency, Azure SQL serverless
6. Local development with Aspire: the AppHost, containers, the dashboard and service defaults
7. Background work and messaging: workers, Service Bus, the outbox, idempotency, dead-lettering
8. GitHub as the team's home: GitHub flow, rulesets, CODEOWNERS, Dependabot, Copilot code review
9. CI with GitHub Actions: build, test, container images without Dockerfiles, CodeQL
10. Choosing Azure services: App Service vs Container Apps vs AKS vs Functions, data, messaging, caching, cost
11. Infrastructure as code: Bicep modules, role assignments, what-if, azd and aspire deploy
12. CD to Azure with OIDC: federated credentials, environments, build once, migrations job, rollback
13. Identity and secrets: managed identity everywhere, Entra auth to SQL and Service Bus, JWT bearer
14. Reliability patterns: retries, timeouts, circuit breakers, graceful degradation, health probes
15. Observability I: logging and OpenTelemetry: structured logs, traces, metrics, context through queues
16. Observability II: Azure Monitor, KQL and SLOs: Application Insights, KQL, alerts, error budgets

Part 3 · Everyday practice

17. Testing strategy: unit and integration tests, Testcontainers, Microsoft.Testing.Platform
18. Performance and scale: HybridCache, async all the way, EF performance, scale rules, load tests
19. Running production: on-call, runbooks, kill switches, safe deploys, postmortems, cost reviews
20. AI-assisted .NET development: GitHub Copilot like a senior, custom instructions, MCP, guardrails

Part 4 · Toolkit

21. Your toolkit: the habits notebook closed, the day-one checklist, what to learn next

Plus the toolkit (cheat sheet, checklists, templates and config files) and the glossary.

Pace

Each chapter takes 20 to 40 minutes to read. Exercises add 15 to 60 minutes.

Run the sample in two minutes

git clone https://github.com/vygantas-meskauskis/cloud-native-dotnet.git
cd cloud-native-dotnet/sample
dotnet build Ledgerly.slnx
dotnet test --solution Ledgerly.slnx   # integration tests need Docker, or set LEDGERLY_TEST_SQL
aspire run                             # needs Docker Desktop or Podman

Start → Chapter 1: From legacy to cloud-native

Chapter 1: From legacy to cloud-native

⏱ About 25 min · You'll learn: what "cloud-native .NET" actually changes for a senior developer, the Ledgerly architecture you will build in this course, and how the 21 chapters fit together.

📖 Story: The whiteboard with no servers on it

It is your first Monday at Ledgerly. Last month you were still at Nordbank Insurance, where "production" meant six Windows Server VMs behind a hardware load balancer, a shared drive full of web.config transforms, and a Thursday-night deployment window where you copied files over Remote Desktop. When something broke, you opened three RDP sessions and searched C:\inetpub\logs and a folder of NLog text files until you found the stack trace.

Maya Okafor, Ledgerly's tech lead, hands you a coffee and walks you to a whiteboard. It shows a few boxes: an API, a worker, a database, a queue, a cache. There are no server names on it, no IP addresses, and no drive letters. "Three rules," she says. "One: there are no servers you can log in to. Two: logs are queries, not files. Three: deploys are boring. They happen on every merge, many times a day, and nobody stays late for them."

You open a new notebook and write a title on the first page: Habits I brought with me. Over the next weeks you will look at each habit honestly, keep the good ones and replace the rest. Maya smiles when she sees it. "Good. Most of your habits are right. The places where they live have changed."

Numbers in the Ledgerly story (team size, timelines, traffic, latency, costs) are illustrative. They make the story concrete; they are not benchmarks.

🏚️ Old way → 🚀 New way

💡 Most of your instincts (clean design, careful SQL, defensive code) still apply. What changed is where the code runs, how it gets there and how you see what it is doing.

🧠 What "cloud-native" means for a .NET developer

"Cloud-native" is used for marketing, so here is a practical definition you can work with. An application is cloud-native when it is designed for an environment where machines are disposable, failures are normal and change is constant. In practice that means a handful of properties:

None of these properties needs Kubernetes, microservices or a specific vendor. Ledgerly is a small system on purpose: one API, one worker, one fake vendor service and one migration job. That is enough to practice every property above without the complexity of fifty services.

💡 Cloud-native is a set of habits, not a technology list. You can build a cloud-native monolith and a very fragile set of microservices.

🧠 What changed in .NET while you were busy

If your last big project was on .NET Framework 4.8, the gap is large but not mysterious. Microsoft rebuilt .NET as a cross-platform, open-source runtime (.NET Core, now just ".NET"), and all new investment goes there.

Sources: .NET support policy and .NET Framework lifecycle.

The other big shift is the hosting model. ASP.NET on .NET Framework was tied to IIS and System.Web. ASP.NET Core runs on its own web server (Kestrel) inside your process. IIS can still front it on Windows, but in a container it is just a process listening on port 8080. That one change explains a lot of this course: once your app is a self-contained process, it can run in a container, on Linux, anywhere.

The hosting model, then and now

🧠 Ledgerly: the product and the team

Ledgerly is a small fintech start-up of about 25 people. It is building a personal investment portfolio tracker, also called Ledgerly. Users can:

• create portfolios and record buys and sells,
• import broker CSV statements (the slow, bursty part),
• see their holdings and a live valuation based on market prices from a third-party vendor,
• set price alerts and get notified.

Version 1 launches as a public beta in about 12 weeks. There is no legacy code: you start greenfield, which is exactly why the team wants to do it "the modern way" from day one.

Your teammates

And you: the senior .NET developer with nine years of IIS, WCF and MVC behind you, and a notebook of habits to examine.

🗺️ The target architecture

This is what you will have running in Azure by chapter 12. Every box is real code or real Bicep in the sample.

flowchart LR
    User["Browser or<br/>React app"] -- "HTTPS + JWT" --> Api
    subgraph ACA["Azure Container Apps environment"]
        Api["api<br/>(Container App)"]
        Worker["worker<br/>(Container App)"]
        Market["marketdata<br/>(internal Container App)"]
        Job["job-migrations<br/>(Container Apps job)"]
    end
    Api -- "EF Core" --> Sql[("Azure SQL<br/>Database")]
    Api -- "prices" --> Market
    Api -. "optional L2 cache" .-> Redis[("Azure Managed<br/>Redis")]
    Worker -- "outbox relay<br/>and imports" --> Bus["Azure Service Bus<br/>queue: imports"]
    Worker -- "EF Core" --> Sql
    Worker -- "prices" --> Market
    Job -- "schema changes" --> Sql
    ACA -- "OpenTelemetry" --> AI["Application Insights<br/>+ Log Analytics"]
    KV["Azure Key Vault"] -. "secret references" .-> Api

And this is how a change gets from your laptop to that environment:

flowchart LR
    Dev["You<br/>(Aspire locally)"] -- "push branch" --> PR["Pull request<br/>(review + checks)"]
    PR -- "merge" --> CI["GitHub Actions: ci<br/>build, test, images, Bicep lint"]
    CI -- "green" --> CD["GitHub Actions: deploy<br/>OIDC sign-in, no secrets"]
    CD -- "push images" --> ACR["Azure Container<br/>Registry"]
    CD -- "Bicep" --> Azure["Azure resources"]
    CD -- "run" --> Mig["Migration job"]
    Mig -- "success" --> Rev["New revisions of<br/>api, worker, marketdata"]
    Rev -- "telemetry" --> Obs["Application Insights<br/>dashboards and alerts"]

Who does what

💻 In Ledgerly: the whole system in one file

You don't need to understand this file yet (chapter 6 explains it line by line). Just notice that the entire local topology, including containers for SQL Server, Redis and a Service Bus emulator, is a C# file you can read and review.

📄 sample/src/Ledgerly.AppHost/AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// ── Infrastructure (containers locally; real Azure services in the cloud, see infra/) ──────────
var sql = builder.AddSqlServer("sql")
    .WithLifetime(ContainerLifetime.Persistent)   // keep the container (and data) between runs
    .WithDataVolume();
var db = sql.AddDatabase("ledgerlydb");

var cache = builder.AddRedis("cache");

var messaging = builder.AddAzureServiceBus("messaging").RunAsEmulator();
messaging.AddServiceBusQueue("imports");
// ...

Compare that with the wiki page you used to maintain about which SQL instance, which MSMQ queue and which IIS site bindings a new developer needed.

🧠 The stack you will learn, and why each piece is there

A note on two names that may surprise you:

• Aspire used to be called ".NET Aspire". The product is now just "Aspire" 🔧.
• Azure Managed Redis is the Redis service for new work. Azure Cache for Redis is being retired in stages 🔧 (chapter 10 has the dates).

mindmap
  root(("Cloud-native .NET"))
    Build
      ".NET 10 and C# 14"
      "Minimal APIs"
      "EF Core 10"
      "Aspire"
    Ship
      "GitHub flow"
      "GitHub Actions CI"
      "Bicep"
      "OIDC deploys"
    Run
      "Container Apps"
      "Managed identity"
      "Resilience"
      "Scaling"
    See
      "OpenTelemetry"
      "Application Insights"
      "KQL and SLOs"
      "On-call and postmortems"

🧠 How this course works

The course has four parts:

Every chapter follows the same shape, so you always know where to look:

Markers you will see

The sample

Everything the chapters quote lives in the sample/ folder of the course repository. It builds with warnings as errors, and its 23 tests (15 unit, 8 integration against a real SQL Server) pass. The CI workflow runs on every push. The deploy workflow stays switched off until you configure your own Azure subscription in chapter 12.

Pace

🧠 Your habits notebook

Maya was right: most of your habits are good. The notebook is a tool for sorting them. Here is the first page, as you write it on day one:

💡 The goal is not to forget what you know. It is to move each habit to the place where it works in the cloud.

⚠️ Common traps

🧰 Helpers

Get the sample on your machine:

git clone https://github.com/vygantas-meskauskis/cloud-native-dotnet.git
cd cloud-native-dotnet/sample
dotnet --list-sdks        # you need a 10.0.x SDK
dotnet build Ledgerly.slnx

What to install before chapter 6:

Make it permanent: keep your own "Habits I brought with me" page. The toolkit has an old-to-new cheat sheet that you can extend as you go. See the toolkit and the glossary for any term you don't recognize.

🧪 Try it yourself (optional, ~15 min)

1. Clone the repository and build the sample: bash cd cloud-native-dotnet/sample dotnet build Ledgerly.slnx
2. Look at the solution layout. Open Ledgerly.slnx in your editor and match each project to the "Who does what" table above.
3. Open src/Ledgerly.AppHost/AppHost.cs and find, without reading the docs, the line that tells the API to wait for the migrations to finish. (Hint: WaitForCompletion.)
4. Run the unit tests (they don't need a database): bash dotnet test --solution Ledgerly.slnx Observe: without a container runtime or the LEDGERLY_TEST_SQL variable, the integration tests are skipped, not failed. Chapter 17 explains why.
5. Write the first page of your own habits notebook: three habits you suspect will change, and one you are sure you'll keep.

✅ Recap

1. Cloud-native means disposable processes, configuration from the environment, everything as code, automated delivery, designed for failure and observable by default.
2. Ledgerly is a small, realistic system (API, worker, fake vendor, migration job) that you will build, ship and run on .NET 10, GitHub and Azure.
3. Your experience still counts. The course moves each habit to where it works today.

Next → Chapter 2: Modern .NET in one sitting

Chapter 2: Modern .NET in one sitting

⏱ About 30 min · You'll learn: how the hosting model, DI and configuration replaced Global.asax and web.config, which C# features you will meet in every Ledgerly file, and which small modern APIs (TimeProvider, Guid.CreateVersion7(), [LoggerMessage]) replace old habits.

📖 Story: "This reads like C# 5"

Your first pull request at Ledgerly is small: a service that values a portfolio. You wrote it the way you wrote hundreds of classes at Nordbank Insurance. A constructor that assigns six private fields. A new HttpClient() inside a using block. DateTime.Now for the timestamp. A .Result on one call because the method above it wasn't async. A log line built with string.Format. And a null check at the top of every method.

Maya's review has one comment at the top, and it is friendly: "This works, and the logic is right. But it reads like C# 5. Let's pair for an hour and I'll show you what changed. Most of it is less code, not more." Below that are twelve inline suggestions, and each one deletes lines.

You open your notebook, Habits I brought with me, and write a new heading: Things the compiler and the framework now do for me. This chapter is that hour with Maya. It is a translation guide, not a tutorial: you already know how to program, so the focus is on what moved and why.

🏚️ Old way → 🚀 New way

💡 The biggest change isn't a language feature. It's that the framework owns startup, DI, configuration and logging, and your code joins that model instead of building its own.

🧠 The hosting model: from IIS to a process you own

On .NET Framework, IIS owned your process. It loaded System.Web, ran Global.asax, pushed the request through HTTP modules and finally reached your controller. You configured half of the behavior in IIS Manager and the other half in web.config.

In ASP.NET Core, your app is the process. The web server, Kestrel, runs inside it. In a Linux container, that process listens on port 8080 by default 🔧 (it used to be 80; set it with ASPNETCORE_HTTP_PORTS). IIS can still sit in front on Windows, but nothing in Ledgerly needs it.

Translation table

There are two builders, and both come from the same generic host (docs): WebApplication.CreateBuilder(args) for anything that serves HTTP (the API, the worker and the market-data service, even if only for health endpoints), and Host.CreateApplicationBuilder(args) for processes with no HTTP surface (the migration service).

💻 In Ledgerly: the API's composition root

📄 sample/src/Ledgerly.Api/Program.cs

var builder = WebApplication.CreateBuilder(args);

// ── Cross-cutting: OpenTelemetry, health checks, resilience, service discovery ────────────────
builder.AddServiceDefaults();

// ── Data: Aspire client integration = DbContext pooling + retries + health check + tracing ──────
builder.AddSqlServerDbContext<LedgerlyDbContext>("ledgerlydb");
// ...
var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseCors(ApiPolicies.Spa);
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
// ...
app.MapPortfolioEndpoints();
app.MapImportEndpoints();
app.MapAlertEndpoints();
app.MapDefaultEndpoints();

app.Run();

Read it as two phases:

1. Before Build(): you describe services. Nothing runs yet. This is where Application_Start code goes.
2. After Build(): you describe the request pipeline. Each Use... line is a middleware, in order. The Map... lines attach endpoints. app.Run() starts Kestrel and blocks until shutdown.

Notice the file is short. Cross-cutting concerns (OpenTelemetry, health checks, retries) come from one call, AddServiceDefaults(), which lives in a shared project (chapter 6). That's the modern answer to the Global.asax you used to copy from project to project.

The migration runner shows the same model without HTTP:

📄 sample/src/Ledgerly.MigrationService/Program.cs

var builder = Host.CreateApplicationBuilder(args);

builder.AddServiceDefaults();
builder.AddSqlServerDbContext<LedgerlyDbContext>("ledgerlydb");
builder.Services.Configure<AppDatabaseUserOptions>(builder.Configuration.GetSection(AppDatabaseUserOptions.Section));
builder.Services.AddHostedService<Migrator>();

builder.Build().Run();

Same configuration, same DI, same telemetry, no web server. Chapter 5 explains what Migrator does.

💡 If you can find it in Program.cs, it happens. If it isn't there, it doesn't. There is no hidden IIS configuration anymore.

🗺️ How a request flows through the API

This is the middleware order from Program.cs, drawn as the path one request takes:

flowchart LR
    Client["Client<br/>browser or SPA"] -- "HTTPS" --> Kestrel["Kestrel<br/>inside the process"]
    Kestrel --> Ex["UseExceptionHandler<br/>errors become ProblemDetails"]
    Ex --> Status["UseStatusCodePages<br/>bare 4xx get a body"]
    Status --> Cors["UseCors<br/>SPA origins only"]
    Cors --> AuthN["UseAuthentication<br/>JWT bearer"]
    AuthN --> AuthZ["UseAuthorization<br/>RequireAuthorization"]
    AuthZ --> Rate["UseRateLimiter<br/>per-user policies"]
    Rate --> Endpoint["Endpoint handler<br/>services injected"]
    Endpoint -- "DbContext" --> Db[("SQL")]

Compare it with the IIS pipeline you knew: the same idea (a chain of steps around your code), but you can see every step, and you choose the order.

🧠 DI, configuration, options and HttpClient

Dependency injection is built in

You don't choose a container anymore, unless you have a strong reason. builder.Services is an IServiceCollection, and every framework feature registers itself there. Three lifetimes cover nearly everything:

The one trap that bites experienced developers: a singleton (like a BackgroundService) must not hold a scoped service such as a DbContext. Create a scope instead. AlertEvaluator takes an IServiceScopeFactory for exactly this reason (chapter 7).

Configuration is layered, not transformed

WebApplication.CreateBuilder reads configuration from several providers, and later ones override earlier ones. A key such as MarketData:BaseUrl in JSON becomes MarketData__BaseUrl as an environment variable (double underscore instead of a colon). That's how the same container image gets different settings in every environment, with no transforms and no rebuild.

flowchart LR
    A["appsettings.json<br/>defaults in git"] --> B["appsettings.Development.json<br/>local overrides"]
    B --> C["User secrets<br/>Development only"]
    C --> D["Environment variables<br/>set by Aspire or Container Apps"]
    D --> E["Command line"]
    E --> Config["IConfiguration<br/>last value wins"]
    Config --> Opt["IOptions of T<br/>typed settings"]
    Config --> Cs["GetConnectionString<br/>ConnectionStrings__ledgerlydb"]

Locally, Aspire injects connection strings as environment variables (chapter 6). In Azure, Bicep sets them on the Container App (chapter 11). Secrets don't go in any of these files at all: chapter 13 replaces them with managed identities.

Options instead of magic strings

The options pattern binds a configuration section to a class once, and code receives a typed object. No more int.Parse(ConfigurationManager.AppSettings["AlertInterval"]) scattered across the codebase.

IHttpClientFactory and typed clients

You probably remember the advice to "make HttpClient static" and then the DNS problems that came with it. The factory manages the underlying handlers for you. A typed client is a class that takes an HttpClient in its constructor, and the registration decides its base address and behavior.

💻 In Ledgerly: the worker's registrations

📄 sample/src/Ledgerly.Worker/Program.cs

builder.Services.AddHttpClient<IMarketDataClient, MarketDataClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["MarketData:BaseUrl"] ?? "https+http://marketdata"));

builder.Services.AddSingleton(TimeProvider.System);
builder.Services.Configure<AlertOptions>(builder.Configuration.GetSection("Alerts"));

builder.Services.AddHostedService<OutboxRelay>();
builder.Services.AddHostedService<ImportProcessor>();
builder.Services.AddHostedService<AlertEvaluator>();

// Give in-flight messages time to finish when Container Apps stops a replica (SIGTERM).
builder.Services.Configure<HostOptions>(o => o.ShutdownTimeout = TimeSpan.FromSeconds(25));

The typed client itself is now almost nothing but HTTP:

📄 sample/src/Ledgerly.Core/Market/MarketDataClient.cs

/// <summary>
/// Typed HttpClient for the market-data service. Base address, retries, timeouts and the circuit breaker
/// are configured at registration time (see ServiceDefaults), not here. This class just speaks HTTP.
/// </summary>
public sealed class MarketDataClient(HttpClient http) : IMarketDataClient
{
    public async Task<IReadOnlyDictionary<string, Quote>> GetQuotesAsync(IReadOnlyCollection<string> symbols, CancellationToken cancellationToken)
    {
        // ...
        var query = Uri.EscapeDataString(string.Join(',', symbols));
        var quotes = await http.GetFromJsonAsync<Quote[]>($"/prices?symbols={query}", cancellationToken) ?? [];
        return quotes.ToDictionary(q => q.Symbol, StringComparer.OrdinalIgnoreCase);
    }
}

Retries, timeouts and the circuit breaker are not in this class. They are added to every HttpClient by ConfigureHttpClientDefaults in the service defaults, using the standard resilience handler (chapter 14).

💡 Configuration says what and where. DI decides who gets it. Your classes just declare what they need in a constructor.

🧠 Async all the way, cancellation and nullability

Async is the default, not an optimization

At Nordbank, async was something you added to a hot path. In ASP.NET Core, the whole stack is async: EF Core, HttpClient, Service Bus, file uploads. Blocking on async code with .Result or .Wait() ties up a thread-pool thread while it waits, and under load that's how you get a service that is "up" but doesn't answer.

CancellationToken: the parameter you'll type a thousand times

In a minimal API handler, a CancellationToken parameter is bound to the request: if the client disconnects, the token fires. In a BackgroundService, the token passed to ExecuteAsync fires on shutdown (SIGTERM from Container Apps). Pass it down to EF Core, HttpClient and the Service Bus SDK, and your app stops cleanly instead of finishing work nobody is waiting for.

💻 In Ledgerly: a loop that stops when the host stops

📄 sample/src/Ledgerly.Worker/AlertEvaluator.cs

public sealed partial class AlertEvaluator(
    IServiceScopeFactory scopes, IMarketDataClient marketData, IOptions<AlertOptions> options, TimeProvider clock,
    ILogger<AlertEvaluator> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(options.Value.IntervalSeconds), clock);
        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await EvaluateAsync(stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                // One bad tick (market data down, DB failover) must not kill the loop.
                LogEvaluationFailed(logger, ex);
            }
        }
    }
    // ...
}

Five modern ideas in twenty lines: a primary constructor, an options object, a TimeProvider-driven PeriodicTimer, a token that ends the loop on shutdown, and an exception filter that lets cancellation through while it logs everything else.

Nullable reference types

Every Ledgerly project has <Nullable>enable</Nullable> (chapter 3). string means "never null" and string? means "might be null". The compiler warns when you dereference something that might be null, and with warnings as errors, that warning stops the build.

💡 Nullable annotations are documentation that the compiler enforces. Treat a ? like a contract, not decoration.

🧠 The C# you will see in every Ledgerly file

net10.0 projects use C# 14 by default (what's new). You skipped a lot of versions. Here are the features that change how everyday code looks, with the version that introduced them and where they show up in Ledgerly.

Source for the versions: C# version history, C# 12 and C# 13.

💻 In Ledgerly: records, primary constructors and collection expressions

📄 sample/src/Ledgerly.Core/Domain/Holdings.cs

namespace Ledgerly.Core.Domain;

public sealed record Holding(string Symbol, decimal Quantity, decimal AverageCost)
{
    public decimal CostBasis => Quantity * AverageCost;
}

public sealed class HoldingsException(string message) : Exception(message);

A positional record gives you a constructor, init-only properties, value equality and a readable ToString() in one line. The exception is a whole class in one line too: the primary constructor passes message to the base class.

One detail that surprises people: in a class with a primary constructor, the parameters are captured, not turned into properties. Only records generate public properties. So MarketDataClient(HttpClient http) keeps http private, which is what you want.

📄 sample/src/Ledgerly.Core/Domain/Portfolio.cs

public sealed class Portfolio
{
    public Guid Id { get; init; } = Guid.CreateVersion7();
    public required string OwnerId { get; init; }
    public required string Name { get; set; }
    public string BaseCurrency { get; init; } = "EUR";
    // ...
    public List<Transaction> Transactions { get; init; } = [];
}

required means an object initializer that forgets OwnerId doesn't compile. = [] is a collection expression: the compiler picks the right construction for List<Transaction>.

💻 In Ledgerly: patterns and raw strings

Pattern matching replaces many small if chains. From the import endpoint:

📄 sample/src/Ledgerly.Api/Endpoints/ImportEndpoints.cs

        if (file.Length is 0 or > MaxFileBytes)
        {
            return TypedResults.ValidationProblem(new Dictionary<string, string[]> { ["file"] = [$"File must be between 1 byte and {MaxFileBytes} bytes."] });
        }

And a property pattern that checks two optional settings and extracts them in one expression, from the migrator:

📄 sample/src/Ledgerly.MigrationService/Program.cs

            if (appUser.Value is { Name: { Length: > 0 } name, ClientId: { Length: > 0 } clientId })
            {
                await strategy.ExecuteAsync(async () => await EnsureAppUserAsync(db, name, Guid.Parse(clientId), stoppingToken));
                LogAppUserEnsured(logger, name);
            }

The same file builds a SQL batch with a raw string literal, so the T-SQL reads like T-SQL:

        var sql = $"""
            IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = N'{user.Replace("'", "''", StringComparison.Ordinal)}')
                CREATE USER [{user}] WITH SID = {sid}, TYPE = E;
            ALTER ROLE db_datareader ADD MEMBER [{user}];
            ALTER ROLE db_datawriter ADD MEMBER [{user}];
            """;

Two C# 14 features worth knowing

The sample doesn't use these yet, but you will see them in new code. Both are from the C# 14 notes.

// illustrative, not in the sample
public sealed class Position
{
    // `field` is the compiler-generated backing field: no private _symbol needed.
    public required string Symbol
    {
        get;
        set => field = value.Trim().ToUpperInvariant();
    }
}

public static class EnumerableExtensions
{
    // Extension members: properties (and static members) on types you don't own.
    extension<T>(IEnumerable<T> source)
    {
        public bool IsEmpty => !source.Any();
    }
}

Use field when a property needs one small rule, and extension members when you want items.IsEmpty instead of items.IsEmpty(). If the logic grows beyond a line, make it a method or a value object instead.

💡 Modern C# mostly removes ceremony. If a feature makes the line shorter and the intent clearer, use it. If it only makes the line shorter, don't.

🧠 Small APIs that replace big habits

TimeProvider: time as a dependency

DateTime.Now in domain code makes tests depend on the clock. TimeProvider is an abstract class in the base library. Production registers TimeProvider.System, and tests pass a FakeTimeProvider that you can move forward.

📄 sample/tests/Ledgerly.UnitTests/PriceTests.cs

        // TimeProvider makes "time" a dependency you can control in tests. No more DateTime.Now in domain code.
        var clock = new FakeTimeProvider(new DateTimeOffset(2026, 10, 28, 12, 0, 0, TimeSpan.Zero));
        var generator = new PriceGenerator(clock);

        var first = generator.GetQuote("aapl");
        clock.Advance(TimeSpan.FromSeconds(20));
        var sameMinute = generator.GetQuote("AAPL");
        clock.Advance(TimeSpan.FromHours(3));
        var later = generator.GetQuote("AAPL");

No Thread.Sleep, no flaky test that fails at midnight.

Guid.CreateVersion7(): IDs that sort

Every Ledgerly entity gets its ID in C#, not from the database: Guid.CreateVersion7(). A version 7 GUID starts with a timestamp, so new IDs are roughly in creation order. You get IDs you can generate before saving (useful for outbox messages and Location headers) without the random insert pattern that made you avoid GUID keys in SQL Server.

There is one sharp edge with client-generated keys in EF Core, and you will hit it in chapter 5.

[LoggerMessage]: structured logs, generated

Old habit: log.InfoFormat("Price for {0} unavailable", symbol). That produces a string, and strings are hard to query. Modern logging uses message templates with named placeholders, and the [LoggerMessage] source generator writes the fast code for you (docs).

📄 sample/src/Ledgerly.Api/Services/ValuationService.cs

public sealed partial class ValuationService(
    LedgerlyDbContext db, IMarketDataClient marketData, HybridCache cache, TimeProvider clock, ILogger<ValuationService> logger)
{
    // ...
    [LoggerMessage(Level = LogLevel.Warning, Message = "Price for {Symbol} unavailable ({Reason}); returning partial valuation")]
    private static partial void LogPriceUnavailable(ILogger logger, string symbol, string reason);
}

The class must be partial so the generator can add the method body. Chapter 15 goes deeper.

What's gone, and where it went

Some things you relied on simply don't exist in .NET 10. This list is from experience, not an exhaustive compatibility matrix. Before you plan a real port of a Nordbank-style app, check the docs for each technology.

.NET Framework 4.8 and 4.8.1 have no announced end date 🔧: they are supported as long as they're installed on a supported Windows version. They just aren't where new features land (lifecycle). Your old apps are fine where they are. New work, like Ledgerly, belongs on .NET 10, which is supported until 2028-11-14 🔧 (support policy).

💡 Most "missing" features were ways to share one big process. In the cloud you share nothing in-process: you split by process, and talk over HTTP or messages.

⚠️ Common traps

🧰 Helpers

Your translation checklist for code review (copy it into your notes):

• [ ] No .Result, .Wait() or async void outside event handlers
• [ ] Every async method takes and passes a CancellationToken
• [ ] Services get dependencies through a (primary) constructor, never new or a static
• [ ] Settings come from an options class, not raw IConfiguration lookups in business code
• [ ] Outbound HTTP uses a typed client registered with AddHttpClient
• [ ] Time comes from TimeProvider, IDs from Guid.CreateVersion7()
• [ ] Logs use templates with named placeholders, and hot paths use [LoggerMessage]
• [ ] DTOs are records, required members are marked required, and nullability is honest

A minimal modern host, if you want to see the bare shape without Ledgerly around it:

// illustrative, not in the sample
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddHostedService<Heartbeat>();
builder.Build().Run();

internal sealed partial class Heartbeat(TimeProvider clock, ILogger<Heartbeat> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(5), clock);
        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            LogTick(logger, clock.GetUtcNow());
        }
    }

    [LoggerMessage(Level = LogLevel.Information, Message = "Tick at {Now}")]
    private static partial void LogTick(ILogger logger, DateTimeOffset now);
}

Make it permanent: don't rely on memory. Chapter 3 turns most of this checklist into build rules: nullable enabled everywhere, file-scoped namespaces and primary constructors in .editorconfig, analyzers at latest-recommended, and warnings as errors. The toolkit's cheat-sheet-old-to-new.md has the old-to-new tables from this chapter on one page (see the toolkit), and the glossary explains terms like generic host and typed client.

🧪 Try it yourself (optional, ~20 min)

1. Read the composition root and map it to your old world: bash cd sample Open src/Ledgerly.Api/Program.cs. For each line before builder.Build(), write down what you would have done in Global.asax or web.config. For each Use... line after it, name the IIS module or web.config section it replaces.
2. Find the modern C# features from the table in the real code. Open src/Ledgerly.Api/Endpoints/PortfolioEndpoints.cs and find a record with validation attributes, a collection expression with a spread, and a handler that takes a CancellationToken.
3. Try the C# 14 features in a file-based app. In a scratch folder outside sample/ (so the sample's strict build settings don't apply), create scratch.cs with the Position class and the extension block from this chapter, plus these top-level lines at the top of the file: csharp // illustrative, not in the sample var p = new Position { Symbol = " vwce " }; Console.WriteLine(p.Symbol); int[] none = []; Console.WriteLine(none.IsEmpty); Console.WriteLine(Guid.CreateVersion7()); Then run it: bash dotnet run scratch.cs Observe: VWCE, True, and a GUID. Run it twice and compare the first characters of the two GUIDs: version 7 GUIDs created later sort later.
4. Build the sample and check that it's clean: bash cd sample dotnet build Ledgerly.slnx

✅ Recap

1. Your app is now the process: Program.cs builds the host (services first, then the middleware pipeline), and DI, configuration and logging are built in.
2. Async with cancellation, nullable reference types, records, primary constructors and collection expressions are the everyday shape of modern C#, and they mostly remove code.
3. Small APIs retire old habits: typed HttpClients, options classes, TimeProvider, Guid.CreateVersion7() and [LoggerMessage].

Next → Chapter 3: A solution set up like a pro

Chapter 3: A solution set up like a pro

⏱ About 30 min · You'll learn: how Ledgerly's repo-wide files (Ledgerly.slnx, Directory.Build.props, Directory.Packages.props, global.json, nuget.config, .editorconfig, local tools) make a fresh clone build the same way everywhere, and why a vulnerable package you never referenced can fail the build.

📖 Story: "Clone it and build it, or it's broken"

On your second day, Tomás hands you a brand-new laptop that has nothing on it but the .NET 10 SDK, Git and Docker. "Ledgerly has one rule," he says. "Clone it and build it on a fresh laptop in one command, or it's broken. No wiki page with twelve setup steps. No 'works on my machine.' If you need a step, it goes in the repo."

You think of Nordbank. The build server had a hand-installed SDK nobody dared to upgrade. Each project had its own packages.config with slightly different versions of Newtonsoft.Json. The analyzers were "on" in one project and silently off in the others. Getting a new developer productive took two days and a senior engineer.

You clone, cd sample, run dotnet build Ledgerly.slnx, and it's green. Then Tomás tells you about the morning it wasn't: nobody had touched a single package, and the build went red with NU1903. A package Ledgerly never referenced directly had a known high-severity vulnerability. "That's the setup working," he says. "I'd rather the build tell me than an auditor." You write in your habits notebook: Build settings are code. They live in the repo, and they fail loudly.

🏚️ Old way → 🚀 New way

💡 A pro setup isn't about clever MSBuild. It's about making the right thing the default, so nobody has to remember it.

🧠 The solution layout and .slnx

Ledgerly has nine projects. The layout is deliberately boring: src/ for things that ship, tests/ for things that verify them, and a handful of repo-wide files at the root.

sample/
├── Ledgerly.slnx
├── Directory.Build.props        compiler and quality settings for every project
├── Directory.Packages.props     every NuGet version, in one place
├── global.json                  SDK pin and test runner
├── nuget.config                 package sources
├── .editorconfig                code style and analyzer severities
├── .config/dotnet-tools.json    local tools (dotnet-ef)
├── src/
│   ├── Ledgerly.AppHost/            Aspire orchestration (chapter 6)
│   ├── Ledgerly.ServiceDefaults/    telemetry, health, resilience
│   ├── Ledgerly.Core/               domain, DbContext, migrations, contracts
│   ├── Ledgerly.Api/                minimal API (chapter 4)
│   ├── Ledgerly.Worker/             background processing (chapter 7)
│   ├── Ledgerly.MarketData/         fake price service
│   └── Ledgerly.MigrationService/   runs migrations, then exits (chapter 5)
└── tests/
    ├── Ledgerly.UnitTests/
    └── Ledgerly.IntegrationTests/

💻 In Ledgerly: the whole solution file

📄 sample/Ledgerly.slnx

<Solution>
  <Folder Name="/src/">
    <Project Path="src/Ledgerly.AppHost/Ledgerly.AppHost.csproj" />
    <Project Path="src/Ledgerly.ServiceDefaults/Ledgerly.ServiceDefaults.csproj" />
    <Project Path="src/Ledgerly.Core/Ledgerly.Core.csproj" />
    <Project Path="src/Ledgerly.Api/Ledgerly.Api.csproj" />
    <Project Path="src/Ledgerly.Worker/Ledgerly.Worker.csproj" />
    <Project Path="src/Ledgerly.MarketData/Ledgerly.MarketData.csproj" />
    <Project Path="src/Ledgerly.MigrationService/Ledgerly.MigrationService.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/Ledgerly.UnitTests/Ledgerly.UnitTests.csproj" />
    <Project Path="tests/Ledgerly.IntegrationTests/Ledgerly.IntegrationTests.csproj" />
  </Folder>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
    <File Path="global.json" />
    <File Path="nuget.config" />
  </Folder>
</Solution>

That's the entire file. No project-type GUIDs, no per-configuration platform matrix, no GlobalSection blocks. When two people add a project on the same day, Git can merge it. dotnet new sln creates .slnx by default from .NET 10 🔧, and Visual Studio 2026 opens it (SDK what's new). To convert an existing .sln, the SDK has a dotnet sln migrate command 🔧 (check the docs for the exact syntax on your SDK).

Project references: who may depend on whom

The layout also encodes the architecture. Ledgerly.Core has no web dependencies, so the API, the worker and the migration runner can all share the domain model and the DbContext.

flowchart TD
    AppHost["Ledgerly.AppHost<br/>Aspire orchestration"]
    Api["Ledgerly.Api"]
    Worker["Ledgerly.Worker"]
    Market["Ledgerly.MarketData"]
    Mig["Ledgerly.MigrationService"]
    Defaults["Ledgerly.ServiceDefaults<br/>telemetry, health, resilience"]
    Core["Ledgerly.Core<br/>domain, DbContext, contracts"]
    Unit["Ledgerly.UnitTests"]
    Int["Ledgerly.IntegrationTests"]
    AppHost --> Api
    AppHost --> Worker
    AppHost --> Market
    AppHost --> Mig
    Api --> Defaults
    Api --> Core
    Worker --> Defaults
    Worker --> Core
    Mig --> Defaults
    Mig --> Core
    Market --> Defaults
    Unit --> Core
    Unit --> Market
    Int --> Api

💡 A project reference is an architectural decision. If a new arrow in this graph surprises you, it should surprise the reviewer too.

🧠 Directory.Build.props: one place for compiler and quality settings

MSBuild automatically imports Directory.Build.props from the project folder upward, and the first one it finds wins (docs). Put one at the solution root and every project gets its settings. You never see <Nullable> or <TargetFramework> in a Ledgerly .csproj.

💻 In Ledgerly: the quality gates

📄 sample/Directory.Build.props

<Project>
  <!-- Applies to every project under this folder. One place for compiler and quality settings. -->
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>

    <!-- Quality gates: warnings fail the build, analyzers and code style run in every build (also in CI). -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <!-- Needed so IDE0005 (unused usings) runs on build. CS1591 = "missing XML comment", not wanted for apps. -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);CS1591</NoWarn>

    <!-- Reproducible, CI-friendly builds. -->
    <Deterministic>true</Deterministic>
    <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
    <RestorePackagesWithLockFile>false</RestorePackagesWithLockFile>
  </PropertyGroup>
</Project>

Analyzers ship with the SDK and are on by default for .NET 5 and later, but only a few rules are warnings out of the box (docs). latest-recommended raises a curated set to warnings, and TreatWarningsAsErrors turns those into errors. If you ever need CA rules to warn without blocking, CodeAnalysisTreatWarningsAsErrors=false exempts them. Ledgerly doesn't use it.

The IDE0005 lesson

When the team first set this up, the .editorconfig said unused usings (IDE0005) should be a warning. In the editor, they were. On dotnet build, nothing happened. The rule depends on information the compiler only produces when it generates the XML documentation file, so IDE0005 only runs on build with GenerateDocumentationFile=true.

Turning that on fixed IDE0005 and broke everything else: now every public type without an XML comment raised CS1591, "missing XML comment", and with warnings as errors, that's an error. Ledgerly is an app, not a library, so the fix was <NoWarn>$(NoWarn);CS1591</NoWarn>. The comment in the file records why, so the next person doesn't "clean it up."

💡 Every line in Directory.Build.props that isn't obvious gets a comment. Build settings are code that people will be tempted to delete.

🧠 Central Package Management, transitive pinning and NuGet audit

With Central Package Management (CPM), Directory.Packages.props holds every package version, and project files only name the package (docs). Upgrading EF Core is now a one-line change, and two projects can't end up on different versions by accident.

💻 In Ledgerly: one file for every version

📄 sample/Directory.Packages.props

<Project>
  <!-- Central Package Management: every NuGet version lives here, projects only name the package. -->
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <!-- Lets a PackageVersion below also override a TRANSITIVE dependency (used for security patches). -->
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup Label="Security pins for transitive dependencies (NuGet audit, NU1902/NU1903)">
    <PackageVersion Include="System.Security.Cryptography.Pkcs" Version="10.0.14" />
  </ItemGroup>
  <!-- ... -->
  <ItemGroup Label="ASP.NET Core and EF Core">
    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.14" />
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.14" />
    <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.14" />
    <PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.14" />
    <!-- ... -->
  </ItemGroup>
  <!-- ... -->
</Project>

And the project side, with no versions at all:

📄 sample/src/Ledgerly.Core/Ledgerly.Core.csproj

  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" PrivateAssets="all" />
  </ItemGroup>

PrivateAssets="all" keeps the EF design-time package (used by dotnet ef) from flowing to projects that reference Core. The ItemGroup labels group packages by purpose, which makes upgrade pull requests easier to review: everything Aspire moves together, and everything ASP.NET Core and EF Core moves together.

Two CPM features Ledgerly doesn't need, but you should know exist:

<!-- illustrative, not in the sample -->
<!-- In one .csproj: an approved exception to the central version -->
<PackageReference Include="Some.Package" VersionOverride="2.0.0" />

<!-- In Directory.Packages.props: added to every project, e.g. an analyzer package -->
<GlobalPackageReference Include="Some.Analyzers" Version="1.0.0" />

Only the nearest Directory.Packages.props applies to a project. If you nest one deeper in the tree, it replaces the root one for that subtree instead of adding to it.

The day NuGet audit failed the build

Here is what Tomás meant. During restore, NuGet checks your packages, including transitive ones (the packages your packages depend on), against known vulnerabilities and reports them as warnings. One morning a transitive dependency, System.Security.Cryptography.Pkcs (versions 9.0.11 and 10.0.12 were in the graph), was flagged: NU1902 (moderate) and NU1903 (high). With TreatWarningsAsErrors, the build failed.

Nobody at Ledgerly had referenced that package. It came in underneath other packages. Without CPM, the usual fix is to add a direct PackageReference to a patched version in every affected project, and to remember to remove it later. With CPM, CentralPackageTransitivePinningEnabled lets a PackageVersion entry override a transitive dependency too. One line in Directory.Packages.props, under a label that says why it's there, and the whole graph moves to the patched version.

flowchart TD
    Restore["dotnet restore"] --> Graph["Resolve package graph<br/>direct and transitive"]
    Graph --> Audit{"NuGet audit<br/>known vulnerabilities?"}
    Audit -- "no" --> Build["Compile, analyzers, code style"]
    Audit -- "yes" --> Warn["NU1902 moderate<br/>NU1903 high"]
    Warn --> Twae["TreatWarningsAsErrors<br/>build fails"]
    Twae --> Pin["Pin patched version<br/>in Directory.Packages.props"]
    Pin --> Transitive["Transitive pinning<br/>overrides the old version"]
    Transitive --> Restore
    Build --> Green["Green build"]

🔧 NuGet audit has settings for severity levels and audit modes. Ledgerly uses the defaults, and this course doesn't depend on any specific value. Check the docs before you tune them. To see what audit sees, list vulnerable packages yourself (the command is in Try it).

💡 A red build caused by a vulnerability is a feature. Pin the fix centrally, label it, and let your dependency bot remove the pin when upstream catches up.

🧠 global.json and nuget.config: same SDK, same sources

Pinning the SDK

📄 sample/global.json

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

version sets the minimum SDK and rollForward decides how far the CLI may move from it (docs). latestFeature means "any .NET 10 SDK at or above 10.0.100, preferring the newest installed feature band." That's a pragmatic middle: everyone builds with .NET 10, but you don't have to install one exact patch to work.

The test section is new in the .NET 10 SDK. It switches dotnet test to Microsoft.Testing.Platform, which xUnit v3 test projects need. Without it, dotnet test on the .NET 10 SDK failed with "Testing with VSTest target is no longer supported by Microsoft.Testing.Platform on .NET 10 SDK." Chapter 17 tells that story in full.

CI uses the same file: the actions/setup-dotnet step reads sample/global.json through its global-json-file input, so the build server can't drift from your laptop (chapter 8).

Locking down package sources

📄 sample/nuget.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Only nuget.org, no machine-wide feeds leaking in. Package source mapping blocks dependency-confusion attacks. -->
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Jonas from security cares about this file more than any other in the repo:

• <clear /> throws away every feed inherited from user-level or machine-level NuGet config. On a laptop that once had a corporate feed configured, restore results no longer depend on that history.
• Package source mapping says which source each package ID may come from. Here it's simple, everything from nuget.org. The value shows up the day you add a private feed: map your internal prefix (say, Ledgerly.*) to the private feed, and an attacker who publishes a package with the same name on a public feed can't sneak in. That attack is called dependency confusion.

💡 global.json decides which compiler builds your code, and nuget.config decides where the code you didn't write comes from. Both belong in git.

🧠 Style, analyzers and local tools

.editorconfig: decisions, not opinions

The .editorconfig at the root sets formatting, naming and analyzer severities for every file. Because EnforceCodeStyleInBuild is on, rules set to warning are checked during build, and with warnings as errors, they block it.

📄 sample/.editorconfig

[*.cs]
# Namespaces and usings
csharp_style_namespace_declarations = file_scoped:warning
dotnet_sort_system_directives_first = true

# Prefer modern syntax
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_prefer_simple_using_statement = true:suggestion
csharp_style_prefer_primary_constructors = true:suggestion
dotnet_style_prefer_collection_expression = when_types_loosely_match:suggestion
# ...
# Analyzer tuning (each line is a deliberate team decision)
dotnet_diagnostic.CA1848.severity = suggestion   # LoggerMessage delegates: we use [LoggerMessage] where it matters
dotnet_diagnostic.CA1515.severity = none         # 'make types internal' is noisy for app code
dotnet_diagnostic.CA1062.severity = none         # nullable reference types already cover argument null checks
dotnet_diagnostic.CA2007.severity = none         # ConfigureAwait(false) is not needed in ASP.NET Core apps
dotnet_diagnostic.CA1716.severity = none
dotnet_diagnostic.IDE0005.severity = warning     # remove unnecessary usings

[**/Migrations/*.cs]
generated_code = true
dotnet_diagnostic.IDE0005.severity = none

[tests/**.cs]
dotnet_diagnostic.CA1707.severity = none         # underscores in test method names are fine
dotnet_diagnostic.CA2000.severity = none

Notice the pattern. Each rule that's turned off has a reason in a comment, so turning a rule off is a reviewed team decision, not a quiet #pragma. Generated code (EF migrations) is marked as generated, so it doesn't fight the style rules. Tests get their own section, because Stale_version_gets_409_conflict is a better test name than StaleVersionGets409Conflict.

Suggestions are the gentle nudge for modern syntax (primary constructors, collection expressions). Warnings are the rules the team agreed are non-negotiable.

dotnet format

dotnet format applies .editorconfig style and analyzer fixes to the code, and dotnet format --verify-no-changes fails if anything would change (docs). Ledgerly's CI doesn't run it as a separate step, because EnforceCodeStyleInBuild already fails the build on the rules that matter. Run it locally to fix a batch of style issues in one go.

Local tools: pinned like packages

dotnet ef is a .NET tool. Installing it globally means every developer has a different version, and some have none. A tool manifest pins it in the repo.

📄 sample/.config/dotnet-tools.json

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-ef": {
      "version": "10.0.14",
      "commands": [
        "dotnet-ef"
      ],
      "rollForward": false
    }
  }
}

dotnet tool restore installs exactly these versions for this repo, and dotnet ef then works inside sample/. The tool version matches the EF Core package version in Directory.Packages.props (10.0.14 🔧), which avoids "tools version is older than runtime" warnings. Keep them in sync when you upgrade.

For a one-off tool you don't want in the manifest, the .NET 10 SDK can run a tool without installing it: dnx <tool> or dotnet tool exec 🔧, for example dnx dotnet-counters when you need runtime counters once.

💡 If a command is part of the workflow, its tool belongs in the manifest. If it's a one-off, use dnx and leave no trace.

🗺️ A fresh clone, end to end

This is Tomás's "one command" rule as a flow. Every box is driven by a file in the repo, not by the machine.

flowchart TD
    Clone["git clone<br/>cd sample"] --> Sdk["global.json<br/>selects a .NET 10 SDK"]
    Sdk --> Sources["nuget.config<br/>nuget.org only"]
    Sources --> Versions["Directory.Packages.props<br/>one version per package"]
    Versions --> Audit["NuGet audit<br/>direct and transitive"]
    Audit --> Props["Directory.Build.props<br/>net10.0, nullable, analyzers"]
    Props --> Style[".editorconfig<br/>style and rule severities"]
    Style --> Compile["Compile all 9 projects"]
    Compile -- "any warning" --> Red["Build fails<br/>fix before merge"]
    Compile -- "clean" --> Green["Green build<br/>same as CI"]

The CI workflow runs exactly the same steps. Its comment says it plainly: "Warnings are errors, analyzers + code style run, NuGet audit fails on vulnerable packages." There is no separate "CI configuration" for quality, which is why a green build on your laptop predicts a green build in CI (chapter 8).

⚠️ Common traps

🧰 Helpers

A starter Directory.Build.props for a new app repo:

<!-- illustrative, not in the sample -->
<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);CS1591</NoWarn>
  </PropertyGroup>
</Project>

Commands you'll use for repo hygiene (run from sample/):

Checklist for a new repo:

• [ ] .slnx solution, src/ and tests/ folders
• [ ] Directory.Build.props with nullable, analyzers, code style in build, warnings as errors
• [ ] Directory.Packages.props with CPM and transitive pinning enabled
• [ ] global.json with an SDK version and rollForward
• [ ] nuget.config with <clear /> and package source mapping
• [ ] .editorconfig with commented severity decisions
• [ ] .config/dotnet-tools.json for every tool the workflow needs
• [ ] CI runs the same dotnet build you run locally

Make it permanent: copy these files from sample/ into your next repo on day one, before the first feature, because tightening rules later means fixing hundreds of warnings at once. Add a Dependabot config (chapter 9) so pinned versions don't rot. The toolkit has ready-to-copy Directory.Build.props, Directory.Packages.props, .editorconfig and dependabot.yml files, and cheat-sheet-old-to-new.md repeats the command table (see the toolkit). Terms like CPM and transitive dependency are in the glossary.

🧪 Try it yourself (optional, ~20 min)

1. Check which SDK the repo selects, and build: bash cd sample dotnet --version dotnet build Ledgerly.slnx The version should be a 10.0 SDK at or above 10.0.100, and the build should end with 0 warnings and 0 errors.
2. Watch a quality gate work. Open src/Ledgerly.Core/Domain/Holdings.cs and add an unused using System.Text; below the namespace line. Build again: bash dotnet build Ledgerly.slnx You should get error IDE0005 (unnecessary using). It's a warning in .editorconfig, and warnings are errors here. Remove the line.
3. Restore the pinned tools and check the EF tool version: bash dotnet tool restore dotnet ef --version It should report 10.0.14, the version in .config/dotnet-tools.json.
4. See what NuGet audit sees: bash dotnet list package --vulnerable --include-transitive With the Pkcs pin in place, you should see no vulnerable packages, unless something new was disclosed since this was written 🔧. If something shows up, you know what to do.
5. Open Ledgerly.slnx and an old .sln from one of your own projects side by side. Count the lines. Write the difference in your habits notebook.

✅ Recap

1. Repo-wide files (Directory.Build.props, Directory.Packages.props, global.json, nuget.config, .editorconfig, the tool manifest) make every clone build the same way on any machine and in CI.
2. Warnings as errors plus latest-recommended analyzers and code style in build turn team agreements into rules the compiler enforces, with every exception commented.
3. CPM with transitive pinning lets NuGet audit fail the build on a vulnerable package you never referenced, and lets you fix it with one labeled line.

Next → Chapter 4: Designing the API

Chapter 4: Designing the API

⏱ About 35 min · You'll learn: how to build a clear HTTP contract with minimal APIs, route groups and TypedResults, how validation, ProblemDetails and OpenAPI 3.1 come almost for free in ASP.NET Core 10, and how CORS, rate limiting, concurrency, async imports and feature flags each map to a status code the frontend can rely on.

📖 Story: Leo needs a contract

Leo, the frontend developer, sits down next to you with a coffee and a list. "I'm starting the React app next sprint. I don't need your code. I need a contract. What are the URLs? What do I send? What comes back when it works, and, more important, what comes back when it doesn't? If one endpoint returns { error: "..." }, another returns plain text and a third returns an HTML error page, I'll write three error handlers and hate you."

At Nordbank, your contract was a Word document with screenshots, and it was out of date the week after it was written. Errors were whatever the controller happened to throw. Leo wants something different: a machine-readable document generated from the code, one error format for everything, and status codes that mean the same thing on every endpoint.

You open your habits notebook and write: The API is a product. Its users are developers, and status codes are part of the UI. Maya adds one rule before you start: "Every response the client can get must be visible in the handler's signature. If it isn't in the type, it doesn't exist."

🏚️ Old way → 🚀 New way

💡 A good API contract is mostly about the unhappy paths. The happy path is easy to agree on.

🧠 Minimal APIs, route groups and typed results

Minimal APIs map a route straight to a method. There's no controller base class and no attribute routing. What you lose in convention you gain in clarity: every endpoint and every policy on it is visible in one place (docs).

A route group applies a prefix, OpenAPI tags, authorization and filters to every endpoint in it. Ledgerly keeps each group in its own file, as an extension method that Program.cs calls.

💻 In Ledgerly: the portfolio routes

📄 sample/src/Ledgerly.Api/Endpoints/PortfolioEndpoints.cs

public static class PortfolioEndpoints
{
    public static IEndpointRouteBuilder MapPortfolioEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/portfolios")
            .WithTags("Portfolios")
            .RequireAuthorization();

        group.MapGet("/", ListPortfolios);
        group.MapPost("/", CreatePortfolio);
        group.MapGet("/{id:guid}", GetPortfolio).WithName("GetPortfolio");
        group.MapPut("/{id:guid}", RenamePortfolio);
        group.MapPost("/{id:guid}/transactions", RecordTransaction);
        group.MapGet("/{id:guid}/valuation", GetValuation);

        return app;
    }
    // ...
}

You can read the whole resource from this block, like a table of contents. RequireAuthorization() on the group means no endpoint in it can be forgotten. {id:guid} is a route constraint: /api/portfolios/abc doesn't match, so it returns 404 without reaching your code.

Handlers are plain static methods. Parameters are bound by type and source: route values, the JSON body, ClaimsPrincipal for the user, services from DI and the request's CancellationToken.

    private static async Task<Results<Ok<PortfolioDetails>, NotFound>> GetPortfolio(
        Guid id, ClaimsPrincipal user, LedgerlyDbContext db, CancellationToken ct)
    {
        var ownerId = user.GetOwnerId();
        var portfolio = await db.Portfolios.AsNoTracking()
            .Include(p => p.Transactions)
            .SingleOrDefaultAsync(p => p.Id == id && p.OwnerId == ownerId, ct);

        if (portfolio is null)
        {
            return TypedResults.NotFound();
        }
        // ...
    }

Why Results<...> matters

The return type Results<Ok<PortfolioDetails>, NotFound> is Maya's rule in code. The compiler only allows those two outcomes, OpenAPI documents both automatically, and a unit test can assert on the result type without an HTTP server. Compare it with the old IHttpActionResult, which could be anything at all.

Notice the ownership check: p.Id == id && p.OwnerId == ownerId. Another user's portfolio returns 404, not 403, so the API doesn't even confirm that the ID exists. An integration test (Users_cannot_see_each_others_portfolios) guards this.

The owner ID comes from the token, through one small extension method:

📄 sample/src/Ledgerly.Api/ApiConventions.cs

    /// <summary>
    /// Stable user id. Entra ID puts the object id in "oid"; dev tokens from `dotnet user-jwts` use "sub"
    /// (mapped to NameIdentifier by the JWT handler).
    /// </summary>
    public static string GetOwnerId(this ClaimsPrincipal user) =>
        user.FindFirstValue("oid")
        ?? user.FindFirstValue("http://schemas.microsoft.com/identity/claims/objectidentifier")
        ?? user.FindFirstValue(ClaimTypes.NameIdentifier)
        ?? user.FindFirstValue("sub")
        ?? throw new InvalidOperationException("Authenticated user has no id claim.");

The same code works with local dev tokens and with Entra ID tokens in Azure. Chapter 13 covers the identity side.

💡 If a status code isn't in the handler's return type, the client should never see it, except for the cross-cutting ones (401, 429, 500) that middleware owns.

🧠 Validation and ProblemDetails: one error shape for everything

Validation with AddValidation()

In ASP.NET Core 10, one line turns on validation for minimal APIs: builder.Services.AddValidation(). A source generator finds the types your handlers take, validates DataAnnotations attributes (and IValidatableObject), and returns 400 with a validation ProblemDetails when something fails. Records are supported, and you can opt an endpoint out with .DisableValidation() (release notes). The validation APIs now live in the Microsoft.Extensions.Validation namespace, so you can reuse them outside ASP.NET Core.

💻 In Ledgerly: requests are records with attributes

📄 sample/src/Ledgerly.Api/Endpoints/PortfolioEndpoints.cs

public sealed record CreatePortfolioRequest(
    [Required, StringLength(100, MinimumLength = 1)] string Name,
    [RegularExpression("^[A-Z]{3}$")] string? BaseCurrency);

public sealed record RenamePortfolioRequest(
    [Required, StringLength(100, MinimumLength = 1)] string Name,
    [Required] string Version);
// ...
public sealed record RecordTransactionRequest(
    [Required, StringLength(12, MinimumLength = 1)] string Symbol,
    TransactionType Type,
    [Range(typeof(decimal), "0.000001", "1000000000")] decimal Quantity,
    [Range(typeof(decimal), "0.000001", "1000000000")] decimal Price,
    DateOnly TradeDate);

The handler never sees an invalid CreatePortfolioRequest. There's no ModelState check, because validation runs before the handler.

Attribute validation covers the shape of input. Business rules still live in the domain. "You cannot sell what you do not hold" needs the portfolio's history, so RecordTransaction checks it and returns the same 400 format by hand:

        try
        {
            // Domain rule: you cannot sell what you do not hold (at that date).
            HoldingCalculator.Calculate([.. portfolio.Transactions, transaction]);
        }
        catch (HoldingsException ex)
        {
            return TypedResults.ValidationProblem(new Dictionary<string, string[]> { ["quantity"] = [ex.Message] });
        }

For Leo, both kinds of failure look identical: a 400 with an errors object keyed by field name. He writes one function that shows field errors next to inputs.

ProblemDetails for every other error

Three registrations in Program.cs give you RFC 9457 application/problem+json responses everywhere (docs):

📄 sample/src/Ledgerly.Api/Program.cs

// ── API surface: validation, ProblemDetails, OpenAPI, JSON ─────────────────────────────────────
builder.Services.AddValidation();
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();
builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.Converters.Add(new JsonStringEnumConverter()));
// ...
app.UseExceptionHandler();
app.UseStatusCodePages();

The integration tests pin this down, so nobody can break it by accident:

📄 sample/tests/Ledgerly.IntegrationTests/PortfolioApiTests.cs

    [Fact]
    public async Task Invalid_input_returns_problem_details()
    {
        var client = ClientFor("alice");

        var response = await client.PostAsJsonAsync("/api/portfolios", new { name = "", baseCurrency = "euro" }, Ct);

        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
        Assert.Equal("application/problem+json", response.Content.Headers.ContentType?.MediaType);
    }

💡 Errors are part of the contract. One format (ProblemDetails), one place to produce it (the framework), and a test that asserts the content type.

🗺️ The status code map Leo gets

Every Ledgerly endpoint follows the same map. Leo prints it and pins it above his desk.

flowchart TD
    Req["Request"] --> Auth{"Valid bearer token?"}
    Auth -- "no" --> R401["401 Unauthorized"]
    Auth -- "yes" --> Rate{"Within rate limit?<br/>imports only"}
    Rate -- "no" --> R429["429 Too Many Requests"]
    Rate -- "yes" --> Flag{"Feature enabled?<br/>alerts only"}
    Flag -- "no" --> R404a["404 Not Found"]
    Flag -- "yes" --> Valid{"Input valid?"}
    Valid -- "no" --> R400["400 validation ProblemDetails"]
    Valid -- "yes" --> Own{"Exists and yours?"}
    Own -- "no" --> R404b["404 Not Found"]
    Own -- "yes" --> Ver{"Version current?"}
    Ver -- "no" --> R409["409 Conflict"]
    Ver -- "yes" --> R2xx["200 OK, 201 Created<br/>or 202 Accepted"]

Anything unexpected becomes a 500 ProblemDetails from the exception handler. Chapter 14 covers the other kind of failure, when a dependency rather than your code is the problem.

🧠 OpenAPI 3.1, Scalar and the versioning decision

The contract, generated

builder.Services.AddOpenApi() plus app.MapOpenApi() serves an OpenAPI document at /openapi/v1.json, and .NET 10 generates OpenAPI 3.1 by default (docs). Your Results<...> return types become the documented responses, the route group's WithTags becomes the grouping, and XML doc comments flow into descriptions. That's one more reason chapter 3 turned on GenerateDocumentationFile: a /// <summary> on a handler like RenamePortfolio ("Optimistic concurrency: the client sends back the Version it read; a stale version gets 409.") shows up in the docs Leo reads.

Swashbuckle is no longer in the project templates 🔧. For a browsable UI, Ledgerly uses Scalar, a third-party package that renders the document at /scalar.

💻 In Ledgerly: docs in development only

📄 sample/src/Ledgerly.Api/Program.cs

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();                 // /openapi/v1.json
    app.MapScalarApiReference();      // /scalar  (interactive API explorer)
}

The interactive explorer stays off in production: there's no reason to hand an attacker a map with a "try it" button. Leo doesn't need production to get the contract. He can generate a TypeScript client from the JSON on a dev machine, or the team can generate the document at build time with Microsoft.Extensions.ApiDescription.Server and commit it.

Versioning: a decision, not a package

Leo asks, "Is it /api/v1/portfolios?" It isn't, and that's deliberate. ASP.NET Core has no built-in API versioning. The common choice is the .NET Foundation package Asp.Versioning.Http (10.2.3 🔧) for minimal APIs.

Ledgerly's only client is its own SPA, deployed from the same repo. The team decided to not version yet, keep changes backward compatible (add fields, never rename or remove them), and add Asp.Versioning.Http the day a third party depends on the API. The sample uses no versioning package. Maya asks you to write that down as an architecture decision record using the toolkit's ADR template, so the "why" survives the people who made it.

💡 Versioning has a cost. Pay it when you have consumers you can't redeploy, not before.

🧠 Protecting the API: CORS and rate limiting

CORS for the SPA

Leo's React dev server runs at http://localhost:5173, and the API runs on a different origin. Browsers block that kind of cross-origin call unless the API says the origin is allowed. Ledgerly reads the allowed origins from configuration, so each environment can list its own front end.

📄 sample/src/Ledgerly.Api/Program.cs

// ── Ready for a React SPA later: allowed origins come from configuration ────────────────────────
var spaOrigins = builder.Configuration.GetSection("Cors:AllowedOrigins").Get<string[]>() ?? [];
builder.Services.AddCors(o => o.AddPolicy(ApiPolicies.Spa, p => p.WithOrigins(spaOrigins).AllowAnyHeader().AllowAnyMethod()));

appsettings.json has an empty list, and appsettings.Development.json adds http://localhost:5173. An empty list by default means "no browser origin is allowed" until someone decides otherwise, which is the safe default. In Azure, the origin comes from an environment variable (Cors__AllowedOrigins__0) set by Bicep (chapter 11).

CORS is a browser rule, not a security boundary for the API. A script or curl ignores it. Authentication (the bearer token) is what protects the data.

Rate limiting the expensive endpoint

Importing a broker CSV is the most expensive thing a user can do. Ledgerly limits it per user with the built-in rate-limiting middleware (docs).

// ── Protection: per-user rate limit for the expensive import endpoint ──────────────────────────
builder.Services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    options.AddPolicy(ApiPolicies.Imports, http => RateLimitPartition.GetFixedWindowLimiter(
        partitionKey: http.User.Identity?.Name ?? http.Connection.RemoteIpAddress?.ToString() ?? "anonymous",
        factory: _ => new FixedWindowRateLimiterOptions { PermitLimit = 5, Window = TimeSpan.FromMinutes(1) }));
});

Three decisions are hiding in those lines:

The policy is attached to just the import endpoint, with .RequireRateLimiting(ApiPolicies.Imports). Policy names live in ApiConventions.cs as constants ("imports", "spa"), so a typo is a compile error, not a policy that silently doesn't apply.

💡 Always set RejectionStatusCode explicitly. A rate limiter that answers 503 makes your own monitoring think the service is down.

🧠 Concurrency, async imports and feature flags

Three endpoints show three more contract patterns Leo will meet.

409 Conflict: optimistic concurrency

Every portfolio response includes a Version string: the database's rowversion, Base64-encoded. To rename, the client sends that version back. If someone else changed the portfolio in between, the update affects zero rows, EF Core throws, and the API returns 409.

        db.Entry(portfolio).Property(p => p.RowVersion).OriginalValue = Convert.FromBase64String(request.Version);
        portfolio.Name = request.Name.Trim();
        portfolio.UpdatedAt = DateTimeOffset.UtcNow;

        try
        {
            await db.SaveChangesAsync(ct);
        }
        catch (DbUpdateConcurrencyException)
        {
            return TypedResults.Problem("Portfolio was changed by someone else. Reload and try again.", statusCode: StatusCodes.Status409Conflict);
        }

For Leo, the rule is simple: on 409, reload and show the user the current data. Chapter 5 explains the database side, and why recording a trade uses the same mechanism to stop a double "sell all."

202 Accepted: work that takes a while

A CSV import can take seconds or minutes. Holding an HTTP request open that long is fragile: a deployment or a scale-in kills it halfway. Instead, the API stores the file, queues the work and answers immediately.

📄 sample/src/Ledgerly.Api/Endpoints/ImportEndpoints.cs

        group.MapPost("/portfolios/{id:guid}/imports", StartImport)
            .RequireRateLimiting(ApiPolicies.Imports)
            // Bearer-token APIs are not vulnerable to CSRF (browsers never attach the token automatically).
            .DisableAntiforgery();
        // ...
    private static async Task<Results<AcceptedAtRoute<ImportStatusResponse>, NotFound, ValidationProblem>> StartImport(
        Guid id, IFormFile file, ClaimsPrincipal user, LedgerlyDbContext db, CancellationToken ct)
    {
        if (file.Length is 0 or > MaxFileBytes)
        {
            return TypedResults.ValidationProblem(new Dictionary<string, string[]> { ["file"] = [$"File must be between 1 byte and {MaxFileBytes} bytes."] });
        }
        // ...
        db.Imports.Add(import);
        db.EnqueueOutboxMessage(Queues.Imports, new ImportRequested(import.Id, id));
        await db.SaveChangesAsync(ct); // one transaction: both rows or neither

        return TypedResults.AcceptedAtRoute(ToResponse(import), "GetImport", new { importId = import.Id });
    }

sequenceDiagram
    participant SPA as "React SPA"
    participant Api as "Ledgerly.Api"
    participant Sql as "Azure SQL"
    participant Worker as "Ledgerly.Worker"
    participant Bus as "Service Bus"
    SPA->>Api: POST /api/portfolios/id/imports with CSV
    Api->>Sql: Insert Import and outbox row in one transaction
    Api-->>SPA: 202 Accepted with Location /api/imports/importId
    Worker->>Sql: Read pending outbox row
    Worker->>Bus: Send ImportRequested
    Bus->>Worker: Deliver ImportRequested
    Worker->>Sql: Save trades and set status Completed
    SPA->>Api: GET /api/imports/importId
    Api-->>SPA: 200 OK with status and row counts

Leo polls the Location URL every couple of seconds until the status is Completed or Failed. Later the team may push a notification instead, but the contract stays the same.

404 when a feature is off

Price alerts are new, and Elena wants to turn them off without a deployment if something goes wrong. Ledgerly uses Microsoft.FeatureManagement.AspNetCore (4.8.0 🔧), with flags read from the FeatureManagement configuration section. appsettings.json has "PriceAlerts": true.

For MVC, the library has a [FeatureGate] attribute that returns 404 when a feature is off. Minimal APIs have no attribute, so Ledgerly wrote a small endpoint filter that does the same for the whole group:

📄 sample/src/Ledgerly.Api/Endpoints/AlertEndpoints.cs

        var alerts = app.MapGroup("/api/alerts")
            .WithTags("Alerts")
            .RequireAuthorization()
            .AddEndpointFilter(RequireFeature(Features.PriceAlerts));
        // ...
    /// <summary>Feature flag gate: when the flag is off the endpoints behave as if they do not exist.</summary>
    private static Func<EndpointFilterInvocationContext, EndpointFilterDelegate, ValueTask<object?>> RequireFeature(string feature) =>
        async (context, next) =>
        {
            var features = context.HttpContext.RequestServices.GetRequiredService<IFeatureManager>();
            return await features.IsEnabledAsync(feature) ? await next(context) : TypedResults.NotFound();
        };

404 is the honest answer: with the flag off, the feature doesn't exist. Leo's app hides the alerts menu on 404. Chapter 19 uses flags like this one as kill switches during an incident.

💡 Every pattern in this section is a status code with a documented client reaction: 409 means reload, 202 means poll, 404 on a flagged feature means hide it.

⚠️ Common traps

🧰 Helpers

A route group template to copy for a new resource:

// illustrative, not in the sample
public static class WatchlistEndpoints
{
    public static IEndpointRouteBuilder MapWatchlistEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/watchlists").WithTags("Watchlists").RequireAuthorization();
        group.MapGet("/{id:guid}", GetWatchlist).WithName("GetWatchlist");
        return app;
    }

    private static async Task<Results<Ok<WatchlistResponse>, NotFound>> GetWatchlist(
        Guid id, ClaimsPrincipal user, LedgerlyDbContext db, CancellationToken ct)
    {
        // Filter by owner in the query, return NotFound otherwise.
        await Task.CompletedTask;
        return TypedResults.NotFound();
    }
}

public sealed record WatchlistResponse(Guid Id, string Name);

Status codes and what the client should do (share this with your frontend team):

API review checklist:

• [ ] Every handler returns TypedResults with a Results<...> signature
• [ ] Request records carry DataAnnotations, and business rules return ValidationProblem
• [ ] Every error is ProblemDetails (application/problem+json)
• [ ] Ownership is enforced in the query, so other users' data returns 404
• [ ] Expensive endpoints have a rate-limit policy, and the rejection code is 429
• [ ] Long work returns 202 with a status URL
• [ ] Updates to shared data carry a version and can return 409

Make it permanent: add the checklist to your pull request template (the toolkit has pr-review-checklist.md and pull_request_template.md, see the toolkit), and back each rule with an integration test like Invalid_input_returns_problem_details and Stale_version_gets_409_conflict. Record the versioning decision with adr-template.md. Terms like ProblemDetails and route group are in the glossary.

🧪 Try it yourself (optional, ~30 min)

You need a container runtime (Docker Desktop or Podman) for Aspire.

1. Start everything: bash cd sample aspire run (Without the Aspire CLI: dotnet run --project src/Ledgerly.AppHost.) Open the dashboard link from the console, and find the API's HTTPS URL on the resources page.
2. Browse the contract: open <api-url>/scalar and <api-url>/openapi/v1.json. Find the responses listed for PUT /api/portfolios/{id} and match them to the Results<...> type in PortfolioEndpoints.cs.
3. Create a dev token in a second terminal: bash cd sample dotnet user-jwts create --project src/Ledgerly.Api Paste the token into src/Ledgerly.Api/Ledgerly.Api.http (the @token line) and set @api to the API URL from the dashboard.
4. Send the requests in the .http file from Visual Studio, Rider or VS Code with an HTTP client extension: create a portfolio (201 with a Location header), then send it again with an empty name (400, application/problem+json).
5. Trigger a 409: get the portfolio, copy its version, and send the same rename twice with that version: ```http # illustrative, not in the sample PUT {{api}}/api/portfolios/ Authorization: Bearer {{token}} Content-Type: application/json

{ "name": "Renamed", "version": "" } `` The first returns 200, the second 409. 6. Trigger a 429: send the "Import a broker CSV" request from the.httpfile six times within a minute. The first five return 202 (or 404 if you didn't replace the portfolio ID), the sixth returns 429. 7. Turn the feature off: stop the app, set"PriceAlerts": falseinsrc/Ledgerly.Api/appsettings.json, run it again, and callPOST /api/alerts. You get 404. Set it back totrue`.

✅ Recap

1. Minimal APIs with route groups and TypedResults put the contract in the code: every possible response is in the handler's Results<...> type, and OpenAPI 3.1 documents it.
2. AddValidation(), ProblemDetails and a fixed status code map (400, 401, 404, 409, 429, 202) give the frontend one error shape and predictable reactions.
3. Protection and evolution are explicit decisions: CORS from configuration, rate limiting with 429 instead of the default 503, Scalar only in development, feature flags as 404, and no versioning until a real consumer needs it.

Next → Chapter 5: Data: EF Core and Azure SQL

Chapter 5: Data: EF Core and Azure SQL

⏱ About 35 min · You'll learn: how Ledgerly wires EF Core 10 through Aspire, how a rowversion turns a double "sell all" into a 409, the EF trap with client-generated keys that the team really hit, why migrations run as their own short-lived process, and how Azure SQL serverless with Entra-only auth removes both idle cost and passwords.

📖 Story: "We sold twice?"

Elena forwards a support ticket with the subject line in capitals. A beta tester had Ledgerly open on her phone and her laptop, tapped Sell All on one, got impatient and clicked it on the other. Her portfolio now shows minus 40 shares of VWCE. "Two clicks at once and we sold twice?" Elena asks. "How is that even possible? We check that you own the shares before selling."

You know exactly how. Both requests read the portfolio at the same moment. Both saw 40 shares. Both passed the check. Both inserted a sell. Each request was correct on its own, and together they were wrong. At Nordbank you would have fixed it with a stored procedure and WITH (UPDLOCK), or by accepting "last write wins" and hoping nobody noticed.

Maya has a different plan: let the database tell you when someone else got there first, and turn that into a clear answer for the second request. In your habits notebook, under Data, you write: Never trust a check you did before someone else's write. This chapter is the fix, plus everything around it: the DbContext, migrations as a deploy step, the EF Core trap that cost the team an afternoon, and the Azure SQL setup that pauses when nobody is using it.

🏚️ Old way → 🚀 New way

💡 Most of what changed is about time and concurrency: many replicas, many requests and a database that can briefly disappear. The SQL itself is the part you already know.

🧠 The DbContext, the model and the indexes

Registering the DbContext through Aspire

In the old world, you'd pass a connection string name to a DbContext constructor and hope web.config had it. In Ledgerly, the API, the worker and the migration service each register the same DbContext with one line:

📄 sample/src/Ledgerly.Api/Program.cs

// ── Data: Aspire client integration = DbContext pooling + retries + health check + tracing ──────
builder.AddSqlServerDbContext<LedgerlyDbContext>("ledgerlydb");

AddSqlServerDbContext comes from the Aspire client integration Aspire.Microsoft.EntityFrameworkCore.SqlServer. It reads the connection string named ledgerlydb (locally from Aspire, in Azure from an environment variable), and it adds retries, a health check and telemetry 🔧. You get a retrying execution strategy without writing EnableRetryOnFailure() yourself, and every query shows up as a span in the traces (chapter 15).

The model, in one place

📄 sample/src/Ledgerly.Core/Data/LedgerlyDbContext.cs

public sealed class LedgerlyDbContext(DbContextOptions<LedgerlyDbContext> options) : DbContext(options)
{
    public DbSet<Portfolio> Portfolios => Set<Portfolio>();
    public DbSet<Transaction> Transactions => Set<Transaction>();
    // ...
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Portfolio>(e =>
        {
            e.Property(p => p.OwnerId).HasMaxLength(128);
            e.Property(p => p.Name).HasMaxLength(100);
            e.Property(p => p.BaseCurrency).HasMaxLength(3).IsFixedLength();
            e.Property(p => p.RowVersion).IsRowVersion();
            e.HasIndex(p => p.OwnerId);
            e.HasMany(p => p.Transactions).WithOne().HasForeignKey(t => t.PortfolioId);
        });

        modelBuilder.Entity<Transaction>(e =>
        {
            e.Property(t => t.Symbol).HasMaxLength(12);
            e.Property(t => t.Type).HasConversion<string>().HasMaxLength(4);
            e.Property(t => t.Quantity).HasPrecision(18, 6);
            e.Property(t => t.Price).HasPrecision(18, 6);
            e.Property(t => t.ExternalRef).HasMaxLength(64);
            e.HasIndex(t => new { t.PortfolioId, t.ExternalRef })
                .IsUnique()
                .HasFilter("[ExternalRef] IS NOT NULL");
        });
        // ...
    }
}

The domain classes stay free of EF attributes (they live in Ledgerly.Core/Domain). Everything about storage is here, in fluent configuration a DBA can review:

A filtered unique index for idempotent imports

The last index deserves a second look. An imported broker row carries an ExternalRef (the broker's own reference, like BRK-1001), and the domain comment says why it matters: "Unique per portfolio, so a re-imported file cannot double-count." Trades typed in by hand have no reference, so the index only applies where one exists. EF Core turns HasFilter into exactly that in the migration:

📄 sample/src/Ledgerly.Core/Data/Migrations/20261028152017_Initial.cs

            migrationBuilder.CreateIndex(
                name: "IX_Transactions_PortfolioId_ExternalRef",
                table: "Transactions",
                columns: new[] { "PortfolioId", "ExternalRef" },
                unique: true,
                filter: "[ExternalRef] IS NOT NULL");

If a user uploads the same CSV twice, the database rejects the duplicates, however the code above it behaves. Chapter 7 shows how the worker uses this for idempotent imports.

💡 Put invariants in the database when you can. Code checks can race, but a unique index can't.

🧠 Optimistic concurrency: how one "sell all" loses

The rowversion column

SQL Server's rowversion is a value the database changes on every update of the row. EF Core includes the value it originally read in the WHERE clause of each UPDATE. If another write got there first, the row no longer matches, zero rows are affected, and EF Core throws DbUpdateConcurrencyException (docs).

📄 sample/src/Ledgerly.Core/Domain/Portfolio.cs

    // Touched on every change (including new trades) so the rowversion check below protects the whole aggregate.
    public DateTimeOffset UpdatedAt { get; set; } = DateTimeOffset.UtcNow;

    // SQL Server rowversion: EF Core uses it for optimistic concurrency.
    public byte[] RowVersion { get; set; } = [];

Here's the subtle part. A new trade is an INSERT into Transactions. Nothing about the Portfolios row changes, so on its own a rowversion on Portfolios would protect nothing. That's why recording a trade also touches UpdatedAt on the portfolio. Now every trade is also an UPDATE of the portfolio row, guarded by its rowversion, in the same transaction.

💻 In Ledgerly: recording a trade

📄 sample/src/Ledgerly.Api/Endpoints/PortfolioEndpoints.cs

        // EF trap: the Id is already set (Guid v7, generated in C#). Adding via portfolio.Transactions would make EF
        // assume the row EXISTS and send an UPDATE (0 rows -> DbUpdateConcurrencyException). Add it explicitly.
        db.Transactions.Add(transaction);
        portfolio.UpdatedAt = DateTimeOffset.UtcNow; // bumps rowversion: two parallel "sell all" requests cannot both win

        try
        {
            await db.SaveChangesAsync(ct);
        }
        catch (DbUpdateConcurrencyException)
        {
            return TypedResults.Problem("Portfolio changed while recording the trade. Retry the request.", statusCode: StatusCodes.Status409Conflict);
        }

Here is the race from Elena's ticket, with the fix in place:

sequenceDiagram
    participant Phone as "Phone"
    participant Laptop as "Laptop"
    participant Api as "Ledgerly.Api"
    participant Sql as "Azure SQL"
    Phone->>Api: POST sell 40 VWCE
    Laptop->>Api: POST sell 40 VWCE
    Api->>Sql: Read portfolio, RowVersion v1, holds 40
    Api->>Sql: Read portfolio, RowVersion v1, holds 40
    Note over Api: Both requests pass the holdings check
    Api->>Sql: Insert trade and update portfolio where RowVersion is v1
    Sql-->>Api: 1 row, commit, RowVersion is now v2
    Api-->>Phone: 201 Created
    Api->>Sql: Insert trade and update portfolio where RowVersion is v1
    Sql-->>Api: 0 rows, EF rolls back the transaction
    Api-->>Laptop: 409 Conflict, retry

When the laptop retries, it reads the new state (0 shares), and the holdings check rejects the sell with a 400. The user sees "you don't hold these shares", which is the truth.

Two flavors of the same mechanism

Ledgerly uses the rowversion in two ways, and it helps to name them:

Both end in DbUpdateConcurrencyException and a 409 ProblemDetails, the contract from chapter 4. If you ever need to show the user what changed, entry.GetDatabaseValues() gives you the current row.

💡 Optimistic concurrency doesn't prevent the race. It makes sure exactly one side wins and the other side knows it lost.

🧠 The EF trap you will hit: client keys added through a navigation

This one is a real story from building Ledgerly, and it will probably happen to you.

Every entity gets its ID in C#: public Guid Id { get; init; } = Guid.CreateVersion7();. The first version of RecordTransaction added the new trade the natural object-oriented way:

// illustrative, not in the sample: the version that failed
portfolio.Transactions.Add(transaction);
portfolio.UpdatedAt = DateTimeOffset.UtcNow;
await db.SaveChangesAsync(ct);

Unit tests were green. Then the integration test against a real SQL Server failed: the buy returned 409, on a portfolio nobody else was touching.

What happened: when EF Core finds a new object through a navigation of a tracked entity, it has to guess whether that object is new or already in the database. For a key that EF expects to generate, a key that's already set means "this row exists." So EF tracked the transaction as an existing row and sent an UPDATE Transactions ... WHERE Id = @id. No such row existed, the update affected 0 rows, and EF reported that the same way it reports a concurrency conflict: DbUpdateConcurrencyException. The endpoint caught it and returned 409, so the bug looked like a concurrency problem when it was really a tracking problem.

flowchart TD
    New["new Transaction<br/>Id = Guid.CreateVersion7"] --> How{"How is it added?"}
    How -- "portfolio.Transactions.Add" --> Guess["EF discovers it via navigation<br/>key already set"]
    Guess --> Existing["Tracked as an existing row"]
    Existing --> Update["UPDATE Transactions<br/>WHERE Id = new id"]
    Update --> Zero["0 rows affected"]
    Zero --> Ex["DbUpdateConcurrencyException<br/>API returns 409"]
    How -- "db.Transactions.Add" --> Added["Tracked as Added"]
    Added --> Insert["INSERT Transactions"]
    Insert --> Ok["201 Created"]

The fix is one line: add the entity through its DbSet, which tells EF explicitly that it's new. The comment in PortfolioEndpoints.cs (in the excerpt above) records why, so nobody "simplifies" it back.

If you want to try the second option, it looks like this:

// illustrative, not in the sample
modelBuilder.Entity<Transaction>().Property(t => t.Id).ValueGeneratedNever();

The bigger lesson is about tests. Only a test that talked to a real SQL Server could catch this, because the in-memory unit tests never sent SQL. Chapter 17 builds those tests with Testcontainers.

💡 With client-generated keys, add new entities through their DbSet. And when a 409 shows up with no second user in sight, suspect tracking before concurrency.

🧠 Migrations as a deploy step

Adding a migration

Migrations live in Ledgerly.Core/Data/Migrations, next to the model. The dotnet ef tool comes from the repo's tool manifest (chapter 3), so everyone uses the same version:

cd sample
dotnet tool restore
dotnet ef migrations add <Name> --project src/Ledgerly.Core --output-dir Data/Migrations

Adding a migration doesn't need a database. The tool builds the DbContext through a design-time factory with a placeholder connection string:

📄 sample/src/Ledgerly.Core/Data/DesignTimeDbContextFactory.cs

/// <summary>
/// Used only by the `dotnet ef` tool at design time (adding migrations, building bundles).
/// The connection string is a placeholder: no database is contacted when adding a migration.
/// </summary>
public sealed class DesignTimeDbContextFactory : IDesignTimeDbContextFactory<LedgerlyDbContext>

Review the generated migration like any other code. The Initial migration shows the rowversion column exactly as configured: RowVersion = table.Column<byte[]>(type: "rowversion", rowVersion: true, nullable: false).

Why not Database.Migrate() at startup?

It's tempting: the app starts, migrates and serves. With one instance on one server, it even works. In the cloud, the API might start as ten replicas at once, and the docs advise against migrating at startup in multi-instance production (docs). Even though EF9 and later take a migration lock, you still have problems: every replica needs schema-change rights, a slow migration delays every replica's readiness, and a failed migration leaves you with half-started apps.

Ledgerly runs migrations in their own process, Ledgerly.MigrationService, which migrates and then exits. The apps don't start until it has finished successfully.

📄 sample/src/Ledgerly.MigrationService/Program.cs

            // The execution strategy retries transient failures (e.g. Azure SQL serverless waking up).
            var strategy = db.Database.CreateExecutionStrategy();
            await strategy.ExecuteAsync(async () => await db.Database.MigrateAsync(stoppingToken));
            LogMigrated(logger);
            // ...
        catch (Exception ex)
        {
            activity?.AddException(ex);
            activity?.SetStatus(ActivityStatusCode.Error);
            LogMigrationFailed(logger, ex);
            Environment.ExitCode = 1; // a failed job execution blocks the deployment pipeline
        }

        lifetime.StopApplication();

Three details matter:

1. The execution strategy. A retrying strategy can't safely replay work it didn't start, so work you run yourself must go through CreateExecutionStrategy().ExecuteAsync(...) (docs). Here it covers the migration and the database-user step, so a paused Azure SQL database that takes a moment to resume isn't a failed deployment.
2. The exit code. On failure, the process exits with code 1. Locally, Aspire shows the resource as failed. In Azure, the migration runs as a Container Apps job, and a failed job execution stops the pipeline before new app revisions roll out (chapter 12).
3. StopApplication(): success or failure, the process ends. A migration runner that keeps running is a bug.

💻 In Ledgerly: the apps wait for completion

📄 sample/src/Ledgerly.AppHost/AppHost.cs

var migrations = builder.AddProject<Projects.Ledgerly_MigrationService>("migrations")
    .WithReference(db)
    .WaitFor(db);

builder.AddProject<Projects.Ledgerly_Api>("api")
    .WithReference(db)
    .WithReference(cache)
    .WithReference(marketData)
    .WaitFor(cache)
    .WaitForCompletion(migrations)
    .WithHttpHealthCheck("/health")
    .WithExternalHttpEndpoints();

WaitFor(db) means "start when the database is healthy." WaitForCompletion(migrations) means "start only after the migrator has exited successfully." The worker has the same line. Locally and in Azure, the order is the same:

flowchart LR
    Sql["SQL database<br/>container or Azure SQL"] -- "healthy" --> Mig["Migration service<br/>run to completion"]
    Mig -- "exit code 0" --> Api["Ledgerly.Api"]
    Mig -- "exit code 0" --> Worker["Ledgerly.Worker"]
    Mig -- "exit code 1" --> Stop["Apps not started<br/>deployment stops"]

Other ways to ship migrations

Whatever you choose, add dotnet ef migrations has-pending-model-changes to CI. It fails when someone changed the model and forgot to add a migration.

💡 A schema change is a deployment step with its own success or failure, not a side effect of an app starting up.

🧠 Azure SQL: serverless, free to start, and no passwords

Serverless and auto-pause

For the beta, Ledgerly uses an Azure SQL serverless database in the General Purpose tier (docs). Compute scales between a minimum (as low as 0.5 vCore) and a maximum, and you're billed per vCore-second of use 💰. When nobody connects for the auto-pause delay (default 60 minutes, minimum 15, -1 disables it), the database pauses and compute billing stops. The first connection after a pause triggers a resume with a short delay, which is why every data access in Ledgerly goes through a retrying execution strategy.

On top of that, the Azure SQL free offer 🔧 gives each database, per month, 100,000 vCore-seconds, 32 GB of data and 32 GB of backup storage, for up to 10 serverless databases per subscription (docs). When the monthly allowance is used up, the database either auto-pauses until next month or continues and bills the overage, depending on a setting 💰.

📄 sample/infra/modules/sql.bicep

    administrators: {
      administratorType: 'ActiveDirectory'
      principalType: 'Application'
      login: adminIdentityName
      sid: adminIdentityClientId // 🔧 for a managed identity, the Learn Bicep sample uses the client id
      tenantId: subscription().tenantId
      azureADOnlyAuthentication: true
    }
// ...
  sku: {
    name: 'GP_S_Gen5_2'
    tier: 'GeneralPurpose'
    family: 'Gen5'
    capacity: 2
  }
  properties: {
    autoPauseDelay: 60
    minCapacity: json('0.5')
    useFreeLimit: useFreeLimit // 💰 100,000 vCore-seconds per month, then pause until next month
    freeLimitExhaustionBehavior: useFreeLimit ? 'AutoPause' : null
  }

For a production system with steady traffic, auto-pause's resume delay may be unacceptable. Chapter 10 compares the options.

Entra-only authentication

azureADOnlyAuthentication: true disables SQL authentication on the server. There are no SQL logins and no passwords: only Microsoft Entra identities can connect (docs). That's Jonas's favorite line in the whole infrastructure.

The apps connect with their managed identity. This is the connection string the Bicep sets on the Container Apps:

📄 sample/infra/modules/apps.bicep

var sqlConnection = 'Server=tcp:${sqlServerFqdn},1433;Database=${databaseName};Authentication=Active Directory Managed Identity;User Id=${identityClientId};Encrypt=True;Connect Timeout=60'

You may see Authentication=Active Directory Default in tutorials. It tries a chain of credentials, which is convenient on a laptop, but the docs note it can be slow and isn't recommended for production. Use the explicit managed identity form in Azure.

Who creates the database user?

An identity that can sign in still needs a user in the database with the right roles. Ledgerly uses two identities: the migration job runs as the SQL admin identity, and the apps run as a separate identity with read and write rights only. After migrating, the migration service creates the app's database user idempotently (EnsureAppUserAsync, with CREATE USER ... WITH SID = ..., TYPE = E) when the Database:AppUser settings are present. Locally those settings aren't set, so the step is skipped. Chapter 11 explains why it uses a SID instead of FROM EXTERNAL PROVIDER, and chapter 13 covers the identities themselves.

💡 The cheapest database is the one that's paused, and the safest password is the one that doesn't exist. Azure SQL serverless with Entra-only auth gives you both.

⚠️ Common traps

🧰 Helpers

EF Core commands (from sample/, after dotnet tool restore):

A concurrency-safe write, the pattern from this chapter in one place:

// illustrative, not in the sample
var order = await db.Orders.SingleOrDefaultAsync(o => o.Id == id && o.OwnerId == ownerId, ct);
if (order is null)
{
    return TypedResults.NotFound();
}

db.Entry(order).Property(o => o.RowVersion).OriginalValue = Convert.FromBase64String(request.Version);
db.OrderLines.Add(new OrderLine { OrderId = order.Id, Sku = request.Sku }); // via the DbSet, not order.Lines
order.UpdatedAt = clock.GetUtcNow();                                         // touch the parent

try
{
    await db.SaveChangesAsync(ct);
}
catch (DbUpdateConcurrencyException)
{
    return TypedResults.Problem("Changed by someone else. Reload and try again.", statusCode: StatusCodes.Status409Conflict);
}

Data checklist for a new service:

• [ ] DbContext registered via the Aspire integration (retries, health check, tracing)
• [ ] Explicit lengths and precision for every string and decimal
• [ ] Business invariants backed by unique (or filtered unique) indexes
• [ ] A rowversion on every aggregate that can be edited concurrently, with 409 on conflict
• [ ] New child entities added via their DbSet
• [ ] Migrations run as a separate step, and the apps wait for it
• [ ] has-pending-model-changes in CI
• [ ] Entra-only auth and a managed identity connection string in Azure

Make it permanent: add dotnet ef migrations has-pending-model-changes as a CI step, and keep at least one integration test that records a trade against real SQL (chapter 17), because that's the test that caught the trap. The toolkit's production-readiness-checklist.md repeats the key ones (migrations as a separate step, managed identities for Azure SQL, 409 on conflicts) (see the toolkit). Terms like rowversion, execution strategy and auto-pause are in the glossary.

🧪 Try it yourself (optional, ~25 min)

None of these steps need a running database, except step 5.

1. Restore the EF tool and look at the migrations: bash cd sample dotnet tool restore dotnet ef --version Open src/Ledgerly.Core/Data/Migrations/20261028152017_Initial.cs and find the rowversion column and the filtered index IX_Transactions_PortfolioId_ExternalRef.
2. Generate the SQL a DBA would review: bash dotnet ef migrations script --idempotent --project src/Ledgerly.Core -o migrate.sql Open migrate.sql. Find CREATE UNIQUE INDEX ... WHERE [ExternalRef] IS NOT NULL and the IF NOT EXISTS checks that make the script safe to run twice. Delete the file when you're done.
3. Catch a forgotten migration. Add a property to Portfolio in src/Ledgerly.Core/Domain/Portfolio.cs, for example public string? Notes { get; set; }, then run: bash dotnet ef migrations has-pending-model-changes --project src/Ledgerly.Core It reports pending changes (a CI step would fail here). Remove the property and run it again: no changes.
4. Read the trap: open src/Ledgerly.Api/Endpoints/PortfolioEndpoints.cs, find the "EF trap" comment in RecordTransaction, and follow the sequence diagram above against the code.
5. Optional, needs Docker: reproduce the trap. Change db.Transactions.Add(transaction); to portfolio.Transactions.Add(transaction); and run the tests: bash dotnet test --solution Ledgerly.slnx The integration tests that record a trade fail, because the setup buy returns 409 instead of 201. Revert the line and run the tests again: all green.

✅ Recap

1. EF Core 10, registered through Aspire's AddSqlServerDbContext, gives you a configured model, retries, health checks and tracing, and invariants like duplicate imports belong in (filtered) unique indexes.
2. A rowversion plus a touched parent turns racing writes into exactly one success and one 409, and client-generated keys must be added via their DbSet to avoid a fake concurrency error.
3. Migrations run as a separate process that the apps wait for, against an Azure SQL serverless database that auto-pauses, uses the free offer, and only accepts Entra identities.

Next → Chapter 6: Local development with Aspire

Chapter 6: Local development with Aspire

⏱ About 30 min · You'll learn: how one C# file (the AppHost) starts SQL Server, Redis, the Service Bus emulator and every Ledgerly service, how connection strings and service addresses reach your code as environment variables, and what the Aspire dashboard and service defaults give you from the first run.

📖 Story: The 14-step wiki page

Your import feature needs everything at once: SQL Server for the data, Redis for the cache, a Service Bus queue for the work, the fake market-data vendor for prices, the API, the worker, and the migrations in front of all of them. At Nordbank Insurance this was the moment you opened the wiki page called "Developer setup". It had 14 steps. Step 4 was "Ask the DBA for a login on DEVSQL02", the shared dev server. Step 9 was "Enable MSMQ in Windows Features and create the private queues by hand". Step 12 said "If the service doesn't start, ask Lars". New joiners lost two days to it, and because everyone shared one SQL Server, one person's half-finished migration broke everybody's afternoon.

Tomás Varga sees you open a blank text file to start your own list. "Don't," he says. "Clone the repo, run aspire run, and the whole system is up. If it takes more than that, it's a bug, and we fix it in the repo, not on a wiki." Maya Okafor pulls up a chair. "And once it's up, you'll see every log, trace and metric from every service in one place. Then we can talk about what happens when the market-data vendor falls over."

In your notebook, under Habits I brought with me, you write: "The dev environment is a document." Then you add a question mark.

🏚️ Old way → 🚀 New way

🧠 What Aspire is, and what it is not

Aspire is a set of tools for describing, running and observing a distributed application. It started as a .NET-only stack and, since version 13, also hosts JavaScript, Python, Java and Rust apps. You will use three parts every day:

A few facts changed recently, so check them before you rely on them (all 🔧):

• The product used to be called ".NET Aspire". The ".NET" prefix was dropped with Aspire 13 (November 2025), and the docs moved to aspire.dev.
• Aspire 13 requires the .NET 10 SDK. The current release line is 13.6, and the sample uses packages and the AppHost SDK at 13.6.4.
• The old dotnet workload install aspire is gone. You install the Aspire CLI instead.

# Windows (PowerShell)
irm https://aspire.dev/install.ps1 | iex

# macOS or Linux
curl -sSL https://aspire.dev/install.sh | bash

# Alternatives: winget install Microsoft.Aspire   or   dotnet tool install -g Aspire.Cli

Source: Install the Aspire CLI.

You also need a container runtime: Docker Desktop or Podman. Aspire runs SQL Server, Redis and the Service Bus emulator as containers. Without a runtime, your projects can start, but their dependencies can't.

Local orchestration first, deployment optional

Aspire can do more than run things on your laptop. aspire publish emits deployment artifacts such as Bicep, and aspire deploy is now the recommended way to deploy an Aspire app to Azure 🔧 (Deploy with Aspire). The Azure Developer CLI (azd) still works, but it is no longer the recommended default for Aspire.

This course uses Aspire for local development only and deploys with hand-written Bicep (chapter 11). That is a teaching choice, not a verdict on aspire deploy:

💡 The AppHost describes your system for development. It is not your production configuration, even though it can generate one.

🧠 The AppHost, line by line

The AppHost is an ordinary .NET project with a special SDK. The version lives in the Sdk attribute, and the four service projects are plain project references:

📄 sample/src/Ledgerly.AppHost/Ledgerly.AppHost.csproj

<Project Sdk="Aspire.AppHost.Sdk/13.6.4">
  <!-- ... -->
  <ItemGroup>
    <ProjectReference Include="..\Ledgerly.Api\Ledgerly.Api.csproj" />
    <ProjectReference Include="..\Ledgerly.Worker\Ledgerly.Worker.csproj" />
    <ProjectReference Include="..\Ledgerly.MarketData\Ledgerly.MarketData.csproj" />
    <ProjectReference Include="..\Ledgerly.MigrationService\Ledgerly.MigrationService.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.SqlServer" />
    <PackageReference Include="Aspire.Hosting.Redis" />
    <PackageReference Include="Aspire.Hosting.Azure.ServiceBus" />
  </ItemGroup>
</Project>

The Aspire.Hosting.* packages are hosting integrations: they teach the AppHost how to run a resource. The services use separate client integrations (for example Aspire.Microsoft.EntityFrameworkCore.SqlServer) to consume it. The versions come from Directory.Packages.props (chapter 3).

💻 In Ledgerly: the infrastructure

📄 sample/src/Ledgerly.AppHost/AppHost.cs

// The whole Ledgerly system, described in C#. `aspire run` (or F5 on this project) starts everything.
var builder = DistributedApplication.CreateBuilder(args);

// ── Infrastructure (containers locally; real Azure services in the cloud, see infra/) ──────────
var sql = builder.AddSqlServer("sql")
    .WithLifetime(ContainerLifetime.Persistent)   // keep the container (and data) between runs
    .WithDataVolume();
var db = sql.AddDatabase("ledgerlydb");

var cache = builder.AddRedis("cache");

var messaging = builder.AddAzureServiceBus("messaging").RunAsEmulator();
messaging.AddServiceBusQueue("imports");

The Service Bus emulator is honest about what it is. It is a Linux container for local development and testing only, it brings its own SQL backing store, and it has limits 🔧: 50 entities, 100 MB per entity, no Entra ID authentication (it uses a connection string with UseDevelopmentEmulator=true) and no persistence, so messages are lost when it restarts (Service Bus emulator overview).

Notice the asymmetry: SQL Server is persistent, the queue is not. If you stop the AppHost while messages are still waiting in imports, they are gone and those imports stay Pending. That is fine for development, and a good reminder that the emulator proves your code paths, not your durability.

💻 In Ledgerly: the services

// ── Services ────────────────────────────────────────────────────────────────────────────────────
var marketData = builder.AddProject<Projects.Ledgerly_MarketData>("marketdata")
    .WithHttpHealthCheck("/health");

var migrations = builder.AddProject<Projects.Ledgerly_MigrationService>("migrations")
    .WithReference(db)
    .WaitFor(db);

builder.AddProject<Projects.Ledgerly_Api>("api")
    .WithReference(db)
    .WithReference(cache)
    .WithReference(marketData)
    .WaitFor(cache)
    .WaitForCompletion(migrations)
    .WithHttpHealthCheck("/health")
    .WithExternalHttpEndpoints();

builder.AddProject<Projects.Ledgerly_Worker>("worker")
    .WithReference(db)
    .WithReference(messaging)
    .WithReference(marketData)
    .WaitFor(messaging)
    .WaitForCompletion(migrations)
    .WithHttpHealthCheck("/health");

builder.Build().Run();

Two details are worth a second look.

First, the reference graph is your architecture. The API references the cache but not Service Bus. The worker references Service Bus but not the cache. That is not an accident: the API never talks to the queue directly; it writes an outbox row in SQL, and the worker publishes it (chapter 7). Anyone reviewing a pull request that adds .WithReference(messaging) to the API should ask why.

Second, WaitForCompletion turns the migration service into a gate. The migrator is a run-to-completion process. If it fails, it sets a non-zero exit code, and the API and worker never start:

📄 sample/src/Ledgerly.MigrationService/Program.cs

        catch (Exception ex)
        {
            activity?.AddException(ex);
            activity?.SetStatus(ActivityStatusCode.Error);
            LogMigrationFailed(logger, ex);
            Environment.ExitCode = 1; // a failed job execution blocks the deployment pipeline
        }

        lifetime.StopApplication();

This is the same contract the Container Apps job follows in Azure (chapter 12): new code never runs against an old schema. You practice the production deployment order every time you press F5.

💡 WaitFor means "is it up?". WaitForCompletion means "did it finish, and did it succeed?". Use the second one for anything that is supposed to exit.

🗺️ The Ledgerly resource graph

This is AppHost.cs drawn as a picture. Solid arrows are references (configuration flows along them). Dotted arrows are start-order gates.

flowchart LR
    subgraph Containers["Containers, started by Aspire"]
        Sql["sql<br/>SQL Server, persistent"]
        Db["ledgerlydb<br/>database"]
        Cache["cache<br/>Redis"]
        Bus["messaging<br/>Service Bus emulator"]
        Queue["imports<br/>queue"]
    end
    subgraph Projects["Your .NET projects"]
        Market["marketdata"]
        Mig["migrations<br/>runs once, exits"]
        Api["api<br/>external endpoints"]
        Worker["worker"]
    end
    Sql --- Db
    Bus --- Queue
    Mig -- "reference" --> Db
    Api -- "reference" --> Db
    Api -- "reference" --> Cache
    Api -- "reference" --> Market
    Worker -- "reference" --> Db
    Worker -- "reference" --> Bus
    Worker -- "reference" --> Market
    Mig -. "must complete first" .-> Api
    Mig -. "must complete first" .-> Worker

🧠 How configuration flows: environment variables, not files

WithReference doesn't do anything magical. When the AppHost starts a project, it sets environment variables on that process. Your code reads them through the normal .NET configuration system, where a double underscore __ in a variable name means : in a configuration key. So ConnectionStrings__ledgerlydb is the same key as "ConnectionStrings": { "ledgerlydb": ... } in appsettings.json.

You don't need to memorize the exact names. Click a resource in the dashboard and its environment variables are listed there, which is the fastest way to answer "what does this service actually see?".

The address https+http://marketdata reads as: "find the service called marketdata, prefer its HTTPS endpoint, fall back to HTTP". The handler that resolves it is added once, in service defaults, for every HttpClient in the process.

💻 In Ledgerly: the same code reads Azure settings

The services never mention containers, ports or passwords. They ask for names:

📄 sample/src/Ledgerly.Api/Program.cs

// ── Data: Aspire client integration = DbContext pooling + retries + health check + tracing ──────
builder.AddSqlServerDbContext<LedgerlyDbContext>("ledgerlydb");
// ...
// ── Outbound HTTP: typed client. Resilience + discovery come from ConfigureHttpClientDefaults. ───
builder.Services.AddHttpClient<IMarketDataClient, MarketDataClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["MarketData:BaseUrl"] ?? "https+http://marketdata"));

In Azure there is no AppHost. Bicep sets the same variable names on the Container App instead:

📄 sample/infra/modules/apps.bicep

          env: concat(commonEnv, [
            { name: 'OTEL_SERVICE_NAME', value: 'worker' }
            { name: 'ConnectionStrings__ledgerlydb', value: sqlConnection }
            { name: 'ConnectionStrings__messaging', value: serviceBusFqns } // a namespace, not a key: Entra auth
            { name: 'MarketData__BaseUrl', value: marketDataUrl }
          ])

💡 Code asks for names. Environments supply values. That is how the same container image runs on your laptop and in production.

🗺️ What happens when you type aspire run

sequenceDiagram
    participant You
    participant CLI as Aspire CLI and AppHost
    participant Runtime as Container runtime
    participant Mig as migrations
    participant Svc as api and worker
    participant Dash as Aspire dashboard
    You->>CLI: aspire run
    CLI->>Dash: start dashboard and OTLP receiver
    CLI->>Runtime: start or reuse sql, cache, messaging
    Runtime-->>CLI: containers healthy
    CLI->>Mig: start with ConnectionStrings__ledgerlydb
    Mig->>Runtime: apply EF Core migrations
    Mig-->>CLI: exit code 0
    CLI->>Svc: start with connection strings and service addresses
    Svc->>Dash: logs, traces and metrics over OTLP
    CLI-->>You: dashboard URL with login token

🧠 The dashboard: your new log folder

At Nordbank, "looking at the logs" meant RDP, a file share and Notepad++. The Aspire dashboard is the local version of what Application Insights will give you in Azure, and it receives the same OpenTelemetry data.

Two things to know 🔧:

• Aspire 13.6 added SQLite-backed dashboard history (What's new in Aspire 13.6).
• The dashboard is also available as a standalone container image, which is handy when you want an OTLP viewer without an AppHost.

The data on the dashboard is only as good as what your services emit. That is the job of service defaults.

🧠 Service defaults: one line of cross-cutting code

Every Ledgerly service starts with builder.AddServiceDefaults(). The method lives in a shared project that started from the Aspire template and was then adapted.

💻 In Ledgerly: what one line adds

📄 sample/src/Ledgerly.ServiceDefaults/Extensions.cs

    public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
    {
        builder.ConfigureOpenTelemetry();
        builder.AddDefaultHealthChecks();

        builder.Services.AddServiceDiscovery();

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            // Retries with jittered back-off, per-attempt + total timeouts, circuit breaker, rate limiter.
            http.AddStandardResilienceHandler();

            // Resolves "https+http://marketdata" to a real address (Aspire locally, config or DNS in Azure).
            http.AddServiceDiscovery();
        });

        return builder;
    }

The tracing setup also filters out the health endpoints, because probes call them every few seconds and would drown the real traffic:

                .AddAspNetCoreInstrumentation(options =>
                    // Probes hit these every few seconds: keep them out of traces.
                    options.Filter = context =>
                        !context.Request.Path.StartsWithSegments(ReadinessPath)
                        && !context.Request.Path.StartsWithSegments(LivenessPath))

One deliberate difference from the template: the template maps /health and /alive only in Development. Ledgerly maps them in every environment, because Container Apps probes need them, and they return a status without details:

    public static WebApplication MapDefaultEndpoints(this WebApplication app)
    {
        // Readiness: all checks (including DB, Redis, Service Bus registered by Aspire integrations).
        app.MapHealthChecks(ReadinessPath).DisableHttpMetrics();

        // Liveness: only checks tagged "live".
        app.MapHealthChecks(LivenessPath, new HealthCheckOptions
        {
            Predicate = r => r.Tags.Contains("live"),
        }).DisableHttpMetrics();

        return app;
    }

💻 In Ledgerly: the chaos switches

Ledgerly.MarketData is the fake vendor. It starts from the Chaos section in its appsettings.json (failure rate 0, latency 0), and in Development it exposes an endpoint that changes those values at runtime:

📄 sample/src/Ledgerly.MarketData/Program.cs

// Chaos controls. Only exposed in Development: never ship a "break me" button to production.
if (app.Environment.IsDevelopment())
{
    app.MapGet("/chaos", (ChaosState chaos) => chaos.Current);
    app.MapPost("/chaos", (ChaosOptions options, ChaosState chaos) =>
    {
        chaos.Set(options);
        return Results.Ok(chaos.Current);
    });
}

ChaosState.Set clamps the values (failure rate between 0 and 1, latency up to 60,000 ms). With chaos on, the /prices endpoint adds latency and returns 503 for a share of requests. Because the API's HttpClient has the standard resilience handler, you can watch the retries happen in the Traces view. Priya will use this switch in chapter 14 to prove the API degrades gracefully instead of failing.

💡 Service defaults make "observable, resilient and discoverable" the default state of a new service instead of a task someone has to remember.

⚠️ Common traps

🧰 Helpers

Install and run:

# once: install the Aspire CLI (see the PowerShell variant above)
curl -sSL https://aspire.dev/install.sh | bash

# every day
cd sample
aspire run                                   # finds the AppHost through aspire.config.json
dotnet run --project src/Ledgerly.AppHost    # same thing without the CLI

Checklist: adding a new service to the system

1. Reference Ledgerly.ServiceDefaults, call builder.AddServiceDefaults() and app.MapDefaultEndpoints().
2. Add the project to AppHost.cs with AddProject<Projects.X>("name").
3. Add .WithReference(...) for each dependency and .WaitFor(...) or .WaitForCompletion(...) for each one that must be ready first.
4. Add .WithHttpHealthCheck("/health").
5. In the service, read connection strings and addresses by name only.

// illustrative, not in the sample: a hypothetical notifications service
builder.AddProject<Projects.Ledgerly_Notifications>("notifications")
    .WithReference(db)
    .WaitForCompletion(migrations)
    .WithHttpHealthCheck("/health");

Reset local data: stop the AppHost, then remove the SQL Server container and its volume with your container tool (docker ps -a, docker volume ls, then docker rm and docker volume rm, or the Podman equivalents). The next aspire run creates a fresh database and the migrator rebuilds the schema.

Make it permanent:

• Replace the "Developer setup" wiki with three lines in the README: install the .NET 10 SDK, install a container runtime and the Aspire CLI, run aspire run. Anything else is a bug to fix in the AppHost.
• The AppHost is part of Ledgerly.slnx, so CI builds it on every pull request (chapter 9). A broken AppHost can't be merged.
• Copy the toolkit's ServiceDefaults.Extensions.cs into new solutions so every service starts observable (see the toolkit).
• In chapter 17 you'll see how the Aspire testing builder starts the whole AppHost inside a test. Terms you don't recognize are in the glossary.

🧪 Try it yourself (optional, ~25 min)

1. Start Docker Desktop or Podman, install the Aspire CLI, then run: bash cd sample aspire run Open the dashboard link the CLI prints.
2. In Resources, watch the order: sql, cache and messaging start first, migrations runs and finishes, and only then do api and worker start. That is WaitForCompletion at work.
3. Click api and look at its environment variables. Find ConnectionStrings__ledgerlydb and the services__marketdata__... entries.
4. Create a development token and copy it: bash dotnet user-jwts create --project src/Ledgerly.Api
5. Open the API's URL from the dashboard and add /scalar (or use src/Ledgerly.Api/Ledgerly.Api.http in your IDE). Create a portfolio, record a buy, then request /api/portfolios/{id}/valuation.
6. In Traces, open the valuation request. Find the span for the call from api to marketdata.
7. Turn on chaos. Take the marketdata URL from the dashboard and send: bash curl -X POST https://localhost:<marketdata-port>/chaos -H "Content-Type: application/json" -d '{"failureRate":0.7,"latencyMs":500}' Quotes are cached for 30 seconds, so wait a moment (or value a portfolio with a different symbol), then request the valuation again. Observe the retry spans in Traces, and isComplete: false when retries run out. Set both values back to 0 when you are done.
8. Stop the AppHost with Ctrl+C and run aspire run again. The SQL container is reused and your portfolio is still there.

✅ Recap

1. The AppHost describes the whole local system in C#: containers, projects, references and start order, so aspire run replaces the setup wiki.
2. References become environment variables, and services read connection strings and addresses by name, which is why the same code runs against containers locally and Azure services in production.
3. Service defaults and the dashboard make every service observable, healthy-checked and resilient from its first run.

Next → Chapter 7: Background work and messaging

Chapter 7: Background work and messaging

⏱ About 35 min · You'll learn: how to move slow work out of the HTTP request with hosted services and an Azure Service Bus queue, how the transactional outbox and an idempotent consumer make "at-least-once" safe, what peek-lock, dead-lettering and duplicate detection do for you, and how a worker shuts down without losing work.

📖 Story: The import that timed out

Elena Rossi forwards a support ticket on Monday morning. A beta user tried to import five years of broker statements, a file of about 15,000 rows (numbers in this story are illustrative). The first prototype parsed the CSV inside the HTTP request, the request ran past the 30-second timeout, and the browser showed an error. So the user clicked Upload again. And again. "What does the user see?" Elena asks. "Right now: an error, and then three copies of some of their trades."

Maya Okafor draws two boxes on the whiteboard, "API" and "worker", and a pipe between them. "The API accepts the file and answers in milliseconds. The worker does the heavy lifting. Now tell me what happens when it fails halfway." You start to answer, and she keeps going: "When the worker crashes after writing half the trades. When the queue delivers the same message twice. When the platform stops the worker in the middle of a file. Every one of those happens in the cloud, and every one has to be boring."

At Nordbank Insurance, background work meant a Windows Service with a System.Timers.Timer polling a "jobs" table, plus a SQL Agent job at 02:00 that nobody dared to touch. In your Habits I brought with me notebook, you write: "Background work runs on one special server that never restarts." Then you cross out "never".

🏚️ Old way → 🚀 New way

🧠 Hosted services: the Windows Service, rebuilt

💡 A BackgroundService is a Windows Service that shares hosting, DI, logging and telemetry with the rest of your app, and that can be stopped at any time.

.NET's generic host runs hosted services (IHostedService) next to everything else in the process. BackgroundService is the convenient base class: you override ExecuteAsync, and the host starts it, passes it a CancellationToken, and signals that token when the process must stop. Ledgerly's worker is three of them in one process:

💻 In Ledgerly: the worker's composition root

📄 sample/src/Ledgerly.Worker/Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddSqlServerDbContext<LedgerlyDbContext>("ledgerlydb");
builder.AddAzureServiceBusClient("messaging");
// ...
builder.Services.AddHostedService<OutboxRelay>();
builder.Services.AddHostedService<ImportProcessor>();
builder.Services.AddHostedService<AlertEvaluator>();

// Give in-flight messages time to finish when Container Apps stops a replica (SIGTERM).
builder.Services.Configure<HostOptions>(o => o.ShutdownTimeout = TimeSpan.FromSeconds(25));

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

Notice WebApplication, not Host: the worker has no API, but it exposes /health and /alive for Container Apps probes (chapter 14). AddAzureServiceBusClient("messaging") is the Aspire client integration. It registers one ServiceBusClient as a singleton, which is what the SDK wants: clients, senders and processors are thread-safe and meant to be reused. Compared with the Windows Service, the biggest change is scaling: there can be more than one replica, so you must design for "more than one".

💻 In Ledgerly: a periodic job with PeriodicTimer

AlertEvaluator checks price alerts every 30 seconds (AlertOptions.IntervalSeconds defaults to 30). It is the replacement for the SQL Agent job:

📄 sample/src/Ledgerly.Worker/AlertEvaluator.cs

/// <summary>
/// Periodically checks active price alerts against live quotes.
/// Run the worker with ONE replica (or move this to a scheduled Container Apps job) so alerts are not evaluated twice.
/// </summary>
public sealed partial class AlertEvaluator(
    IServiceScopeFactory scopes, IMarketDataClient marketData, IOptions<AlertOptions> options, TimeProvider clock,
    ILogger<AlertEvaluator> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(options.Value.IntervalSeconds), clock);
        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await EvaluateAsync(stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                // One bad tick (market data down, DB failover) must not kill the loop.
                LogEvaluationFailed(logger, ex);
            }
        }
    }

Four habits are packed into those lines:

1. PeriodicTimer instead of System.Timers.Timer. You await the next tick, so a slow tick can't overlap the next one, and cancellation ends the loop cleanly.
2. TimeProvider clock is injected, so tests can control time instead of waiting 30 seconds (chapter 17).
3. A new DI scope per tick (scopes.CreateAsyncScope() inside EvaluateAsync). A hosted service is a singleton, and a DbContext must not live that long.
4. Catch everything except cancellation. An exception that escapes ExecuteAsync ends the loop for good (and by default the host stops too), and one failed market-data call must not end alert checking.

Two replicas, two evaluations

Read the comment again: a timer loop runs in every replica, so two replicas can trigger the same alert at nearly the same moment and create two notifications. The Windows Service never had this problem because there was only one of it. In Azure, the worker has minReplicas: 1 (so the timers always run) and scales out on queue length, which is exactly when a second AlertEvaluator appears. You have three options:

Container Apps jobs run finite tasks and support three trigger types: Manual, Schedule (cron) and Event (a KEDA scaler such as a Service Bus queue) (Jobs in Azure Container Apps). Ledgerly already runs its migrations as a job with triggerType: 'Manual' (📄 sample/infra/modules/migration-job.bicep). A scheduled alert job would change only the trigger:

// illustrative, not in the sample: run the alert check every 5 minutes as a job
    configuration: {
      triggerType: 'Schedule'
      replicaTimeout: 300
      replicaRetryLimit: 0
      scheduleTriggerConfig: { cronExpression: '*/5 * * * *', parallelism: 1, replicaCompletionCount: 1 }
    }

💰 A job that runs for a few seconds every few minutes costs less than a replica that is always on. It also needs its own entry point (a console app that runs one evaluation and exits), which is the price of the split.

🧠 Azure Service Bus queues: peek-lock, retries and the dead-letter queue

💡 A queue doesn't make failures go away. It gives every failure a defined next step: try again, or park the message for a human.

A Service Bus queue is point-to-point: senders put messages in, and competing consumers take them out, so you can add workers to drain it faster. That is load leveling, and it is why a burst of imports doesn't hurt the API.

The important part is how a message is received. In PeekLock mode (the default) the receiver gets the message with a lock, and must then settle it:

(A fourth action, Defer, sets a message aside to fetch later. Ledgerly doesn't use it.)

That gives you at-least-once delivery: a message is only removed when someone completes it. The alternative, ReceiveAndDelete, removes the message on receipt (at-most-once), so a crash loses it. For imports, losing work is worse than doing it twice, as long as doing it twice is harmless.

Three queue settings turn this into a safety net:

• MaxDeliveryCount (default 10). After that many deliveries, Service Bus moves the message to the dead-letter queue (DLQ), a sub-queue at <entity>/$deadletterqueue, with a reason such as MaxDeliveryCountExceeded. DLQ messages are never deleted automatically, so somebody has to watch them (chapter 16 covers alerting) (Dead-letter queues).
• Duplicate detection. The queue remembers every MessageId it saw within a time window (default 10 minutes, configurable from 20 seconds to 7 days) and drops repeats. It must be enabled when the queue is created (Duplicate detection).
• Dead-lettering on expiration. Messages whose time-to-live runs out go to the DLQ instead of disappearing.

💻 In Ledgerly: the queue, as code

📄 sample/infra/modules/servicebus.bicep

// Service Bus Standard (needed for duplicate detection). Local (SAS key) auth is disabled:
// only Entra identities with a data role can send or receive.
// ...
  sku: { name: 'Standard', tier: 'Standard' }
  properties: {
    disableLocalAuth: true
    // ...
resource imports 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  parent: namespace
  name: 'imports'
  properties: {
    lockDuration: 'PT1M'
    maxDeliveryCount: 10 // after 10 failed attempts the message moves to imports/$deadletterqueue
    requiresDuplicateDetection: true // the same MessageId within the window is dropped
    duplicateDetectionHistoryTimeWindow: 'PT10M'
    deadLetteringOnMessageExpiration: true
  }
}

lockDuration: 'PT1M' is how long the worker holds a message before Service Bus assumes it died and offers the message to someone else. disableLocalAuth: true means no connection-string keys at all: the worker's managed identity gets the Azure Service Bus Data Sender and Data Receiver roles further down the same file (chapter 13).

The tier matters 🔧 💰. Basic has no duplicate detection, sessions or transactions, so Ledgerly uses Standard (shared capacity, pay per operation). Premium adds dedicated Messaging Units, VNet and Private Link, and messages up to 100 MB, at a fixed cost even when idle.

One honest gap: locally, the AppHost declares the queue with messaging.AddServiceBusQueue("imports") and no extra settings, so the emulator queue has no duplicate detection window. The idempotent consumer below is what keeps local runs correct, which is a good argument for never relying on duplicate detection alone.

🗺️ The life of an import message

flowchart TD
    Send["Relay sends message<br/>MessageId = outbox id"]
    Dup{"MessageId seen in<br/>last 10 minutes?"}
    Drop["Dropped by<br/>duplicate detection"]
    Queue["Waiting in<br/>imports queue"]
    Locked["Delivered with a lock<br/>to one worker"]
    Done["Completed<br/>message deleted"]
    Retry{"Delivery count<br/>below 10?"}
    Dlq["Dead-letter queue<br/>waits for a human"]
    Send --> Dup
    Dup -- "yes, in Azure" --> Drop
    Dup -- "no" --> Queue
    Queue --> Locked
    Locked -- "complete" --> Done
    Locked -- "abandon or lock expires" --> Retry
    Retry -- "yes" --> Queue
    Retry -- "no" --> Dlq
    Locked -- "dead-letter: ImportNotFound" --> Dlq

🧠 The transactional outbox: never lose the message

💡 If the database and the queue can't share a transaction, put the message in the database and send it later.

Here is the bug you would write by habit:

// illustrative, not in the sample: the dual-write bug
db.Imports.Add(import);
await db.SaveChangesAsync(ct);                                   // 1. committed
await sender.SendMessageAsync(new ServiceBusMessage(json), ct);  // 2. what if this throws?

If step 2 fails (a network blip, a throttled namespace, a deployment that kills the process), the import row exists but no message does. The import stays Pending forever. Swap the order, and you get the opposite bug: a message about an import that was rolled back. SQL Server and Service Bus can't take part in one transaction, so you need a different shape.

The transactional outbox writes the message as a row in the same database, in the same transaction as the business change. A separate relay reads unsent rows and publishes them. EnqueueOutboxMessage only adds the row: it is saved by the caller's next SaveChangesAsync.

💻 In Ledgerly: the outbox row

📄 sample/src/Ledgerly.Core/Messaging/Outbox.cs

public sealed class OutboxMessage
{
    public Guid Id { get; init; } = Guid.CreateVersion7();
    public required string Type { get; init; }
    public required string Destination { get; init; }
    public required string Payload { get; init; }
    public DateTimeOffset OccurredAt { get; init; } = DateTimeOffset.UtcNow;
    public DateTimeOffset? ProcessedAt { get; set; }
    public int Attempts { get; set; }
    public string? LastError { get; set; }

    // W3C trace context of the request that created the message, so the trace continues in the worker.
    public string? TraceParent { get; init; }
}
// ...
    public static void EnqueueOutboxMessage<T>(this LedgerlyDbContext db, string destination, T message)
    {
        db.OutboxMessages.Add(new OutboxMessage
        {
            Type = typeof(T).Name,
            Destination = destination,
            Payload = JsonSerializer.Serialize(message),
            TraceParent = System.Diagnostics.Activity.Current?.Id,
        });
    }

Guid.CreateVersion7() gives time-ordered IDs, which index well. TraceParent captures the current trace, so the worker's spans appear under the original HTTP request in the dashboard (chapter 15).

💻 In Ledgerly: the API side, one SaveChanges

📄 sample/src/Ledgerly.Api/Endpoints/ImportEndpoints.cs

        db.Imports.Add(import);
        db.EnqueueOutboxMessage(Queues.Imports, new ImportRequested(import.Id, id));
        await db.SaveChangesAsync(ct); // one transaction: both rows or neither

        return TypedResults.AcceptedAtRoute(ToResponse(import), "GetImport", new { importId = import.Id });

EF Core wraps one SaveChangesAsync in one transaction, so either both rows exist or neither does. The endpoint returns 202 Accepted with a Location header pointing at GET /api/imports/{importId}, which the client polls. The endpoint is also rate-limited (five uploads per user per minute) and rejects files over 1,000,000 bytes, so the "click Upload three times" problem can't turn into a flood.

💻 In Ledgerly: the relay

📄 sample/src/Ledgerly.Worker/OutboxRelay.cs

    private const int BatchSize = 20;
    private const int MaxAttempts = 10;
    // ...
        var pending = await db.OutboxMessages
            .Where(m => m.ProcessedAt == null && m.Attempts < MaxAttempts)
            .OrderBy(m => m.OccurredAt)
            .Take(BatchSize)
            .ToListAsync(ct);
        // ...
                var sender = _senders.GetOrAdd(message.Destination, serviceBus.CreateSender);
                await sender.SendMessageAsync(
                    new ServiceBusMessage(message.Payload)
                    {
                        MessageId = message.Id.ToString(),
                        Subject = message.Type,
                        ContentType = "application/json",
                    },
                    ct);

                message.ProcessedAt = clock.GetUtcNow();

Every 2 seconds (PeriodicTimer, again), the relay takes up to 20 unsent rows in order, sends each one, and marks it processed. A failed send increments Attempts and stores LastError. After 10 attempts the row is skipped, so one broken message can't block the rest, and the row stays in the table for someone to investigate.

The class comment names the weak spot: delivery is at-least-once, because if the worker crashes after SendMessageAsync but before SaveChangesAsync, the next tick sends the same row again. The same happens if two worker replicas pick up the same batch. That is why MessageId = message.Id.ToString() matters: the duplicate carries the same ID, so Service Bus duplicate detection drops it in Azure, and the consumer recognizes it everywhere.

🗺️ From upload to processed import

sequenceDiagram
    participant User
    participant Api
    participant Sql as Azure SQL
    participant Relay as OutboxRelay
    participant Bus as Service Bus imports
    participant Proc as ImportProcessor
    User->>Api: POST imports with CSV
    Api->>Sql: insert Import and OutboxMessage in one transaction
    Api-->>User: 202 Accepted with Location
    Relay->>Sql: read unsent outbox rows
    Relay->>Bus: send with MessageId = outbox id
    Relay->>Sql: set ProcessedAt
    Bus->>Proc: deliver with peek-lock
    Proc->>Sql: already in ProcessedMessages?
    Proc->>Sql: trades, import status and ProcessedMessage in one SaveChanges
    Proc->>Bus: complete
    User->>Api: GET import status
    Api-->>User: Completed, rows imported and skipped

🧠 The idempotent consumer: processing twice changes nothing

💡 You can't get exactly-once delivery, but you can get exactly-once effects.

At-least-once delivery means your handler will see some messages twice: relay re-sends, abandoned messages, a lock that expired while a slow import was still running. The handler's job is to make the second time a no-op.

💻 In Ledgerly: the handler

📄 sample/src/Ledgerly.Worker/ImportProcessor.cs

    private async Task HandleAsync(ProcessMessageEventArgs args)
    {
        var messageId = args.Message.MessageId;
        // ...
        if (await db.ProcessedMessages.AnyAsync(p => p.MessageId == messageId, ct))
        {
            LogDuplicate(logger, messageId);
            await args.CompleteMessageAsync(args.Message, ct);
            return;
        }
        // ...
        if (import is null)
        {
            // Poison message: retrying will never help. Park it in the DLQ for a human to look at.
            await args.DeadLetterMessageAsync(args.Message, "ImportNotFound", $"No import for message {messageId}", ct);
            return;
        }

        try
        {
            var outcome = await ApplyImportAsync(db, import, ct);
            db.ProcessedMessages.Add(new ProcessedMessage { MessageId = messageId, Handler = HandlerName });
            await db.SaveChangesAsync(ct); // trades + import status + idempotency record in ONE transaction
            await args.CompleteMessageAsync(args.Message, ct);
            // ...
        }
        catch (Exception ex) when (ex is not OperationCanceledException)
        {
            // ...
            await args.AbandonMessageAsync(args.Message, cancellationToken: ct); // Service Bus will redeliver
        }
    }

Walk through it the way Maya would:

Three design choices make this work:

1. AutoCompleteMessages = false in the ServiceBusProcessorOptions. The processor never completes a message on your behalf. You complete it only after the transaction committed.
2. The idempotency record is in the same transaction as the work. Trades, import status and the ProcessedMessage row are saved by one SaveChangesAsync. There is no moment where the trades exist but the record doesn't.
3. The database enforces it, not just the code. ProcessedMessage uses MessageId as its primary key. If two replicas handle the same message at the same moment, both pass the AnyAsync check, but only one insert can succeed. The other gets an exception, abandons, and on redelivery completes as a duplicate.

There is a third layer, in the data model itself. Each broker row's reference is stored as Transaction.ExternalRef, with a filtered unique index on (PortfolioId, ExternalRef) (chapter 5), and ApplyImportAsync skips references the portfolio already has. Re-uploading the same file imports zero new rows and reports them as skipped. That fixes Elena's ticket from the user's side.

The processor also sets MaxConcurrentCalls = 4, so one replica handles four imports in parallel. Each call gets its own DI scope and DbContext, because a DbContext is not thread-safe.

🧠 Graceful shutdown and boring parsing

💡 In the cloud, your process is stopped on purpose many times a day. Make stopping a normal code path.

Container Apps stops replicas when it scales in and when it rolls out a new revision. It sends SIGTERM, and the .NET host then stops accepting new work, signals the CancellationToken passed to ExecuteAsync, and calls StopAsync on every hosted service. HostOptions.ShutdownTimeout caps how long that may take: the default is 30 seconds, and Ledgerly sets 25 so it finishes inside the platform's termination grace period (❓ Container Apps' default is believed to be 30 seconds but this course hasn't re-verified it) (.NET Generic Host).

💻 In Ledgerly: stop taking messages, finish the ones in flight

📄 sample/src/Ledgerly.Worker/ImportProcessor.cs

    public override async Task StopAsync(CancellationToken cancellationToken)
    {
        // Graceful shutdown: stop taking new messages, let in-flight handlers finish.
        if (_processor is not null)
        {
            await _processor.StopProcessingAsync(cancellationToken);
            await _processor.DisposeAsync();
        }

        await base.StopAsync(cancellationToken);
    }

If an import is still running when the timeout hits, its cancellation token fires, SaveChangesAsync never commits, and the message is never completed. Peek-lock then gives the message to another replica after the lock expires, and the idempotent handler starts from a clean state. A Windows Service killed mid-job left half a batch behind. This one leaves nothing behind, which is the point of putting the whole effect in one transaction.

OutboxRelay.StopAsync does the same in its own way: it lets the loop end, then disposes its cached senders.

💻 In Ledgerly: a parser that doesn't care where it runs

Background work runs on machines you never see, with cultures you didn't choose. BrokerCsvParser parses every number and date with the invariant culture, and it reports bad rows instead of throwing:

📄 sample/src/Ledgerly.Core/Imports/BrokerCsvParser.cs

/// <summary>
/// Parses the broker export format:
/// <c>date,type,symbol,quantity,price,reference</c> (header required, ISO dates, invariant decimals).
/// Bad rows are reported, not thrown: one typo should not reject a 5 000-row file.
/// </summary>
public static class BrokerCsvParser
{
    // ...
            if (!decimal.TryParse(cells[4], NumberStyles.Number, CultureInfo.InvariantCulture, out var price) || price <= 0)
            {
                errors.Add(new ParseError(lineNumber, $"Invalid price '{cells[4]}'."));
                continue;
            }

A unit test proves it by switching the thread to lt-LT, where the decimal separator is a comma:

📄 sample/tests/Ledgerly.UnitTests/BrokerCsvParserTests.cs

    public void Decimal_parsing_ignores_server_culture()
    {
        // The old IIS box had lt-LT culture and "190,10" broke imports. Invariant culture, always.
        var previous = Thread.CurrentThread.CurrentCulture;
        Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("lt-LT");
        try
        {
            var result = BrokerCsvParser.Parse($"{Header}\n2026-09-01,buy,AAPL,5,190.10,BRK-1");
            Assert.Equal(190.10m, Assert.Single(result.Trades).Price);
        }
        // ...

"Reported, not thrown" also matters for the queue. A parse error is a business result, saved on the import (completed_with_errors, with the first five errors in Error). If it were an exception, the message would be abandoned and retried 10 times, with the same result every time, and then dead-lettered. Only throw for things a retry can fix.

⚠️ Common traps

🧰 Helpers

Checklist: a new message type

1. Define the message as a small record with IDs, not whole entities (like ImportRequested(ImportId, PortfolioId)).
2. Enqueue it with db.EnqueueOutboxMessage(...) before the one SaveChangesAsync of the request.
3. In the consumer: check ProcessedMessages, do the work, add the ProcessedMessage, save once, then complete.
4. Decide, for each failure, which settle action it gets: abandon for transient faults (timeouts, throttling), dead-letter for messages that can never succeed, complete for business outcomes you recorded.
5. Add a test that delivers the same message twice and asserts that nothing changes the second time (chapter 17).

Make it permanent:

• Add "What happens when this message is delivered twice?" to your pull request review checklist, for example the toolkit's pr-review-checklist.md (see the toolkit).
• Keep queue settings (maxDeliveryCount, duplicate detection, dead-lettering) in Bicep next to the code that depends on them, so a reviewer sees both in one pull request (chapter 11).
• Write down the rule "one SaveChanges per message, complete after commit" in your team's ADRs. Terms such as outbox and idempotency are in the glossary.

🧪 Try it yourself (optional, ~30 min)

1. Start the system and create a token: bash cd sample aspire run dotnet user-jwts create --project src/Ledgerly.Api
2. Open src/Ledgerly.Api/Ledgerly.Api.http in your IDE, set @api to the API's URL from the dashboard and @token to your token, and create a portfolio. Copy its id.
3. Save this as broker.csv: text date,type,symbol,quantity,price,reference 2026-09-01,buy,AAPL,5,190.10,BRK-1001 2026-09-15,buy,MSFT,3,410.00,BRK-1002 2026-09-20,buy,MSFT,abc,410.00,BRK-1003
4. Upload it (replace the URL, ID and token): bash curl -i -X POST https://localhost:7180/api/portfolios/<id>/imports -H "Authorization: Bearer <token>" -F "file=@broker.csv" You get 202 Accepted and a Location header right away.
5. Request the Location URL (with the same Authorization header) until the status is Completed. Expect 2 rows imported and 1 skipped, with "Invalid quantity" in error.
6. Upload the same file again. The second import completes with 0 rows imported and all rows skipped: idempotency by ExternalRef.
7. In the dashboard's Traces view, find the POST request. The worker's outbox publish imports span appears in the same trace: that is the TraceParent column at work. Then find the import process span for the same import (chapter 15 explains how trace context crosses the queue).
8. Stop the AppHost and run the unit tests, including the lt-LT parser test: bash dotnet test --solution Ledgerly.slnx

✅ Recap

1. Slow work leaves the HTTP request: the API returns 202, and hosted services in the worker do the work with PeriodicTimer loops and a Service Bus processor.
2. The transactional outbox guarantees the message is sent if and only if the data was saved, and the idempotent consumer (one transaction plus a primary key) makes at-least-once delivery safe.
3. Peek-lock, MaxDeliveryCount, the dead-letter queue and graceful shutdown give every failure a defined next step, so stopping or crashing a worker never leaves half an import behind.

Next → Chapter 8: GitHub as the team's home

Chapter 8: GitHub as the team's home

⏱ About 30 min · You'll learn: how a change travels from a short-lived branch to main through a pull request, how rulesets, required checks and CODEOWNERS turn team rules into settings GitHub enforces, and how Dependabot, CodeQL, secret scanning and Copilot code review keep watch without a meeting.

📖 Story: Your first pull request

The background import from chapter 7 works on your machine. The Service Bus emulator drains the queue, the duplicate test passes, and Elena's support ticket can finally be closed. At Nordbank Insurance, this is where the waiting began. Your work would sit on a branch called release/2019-Q3 for weeks. Someone would zip a diff and email it to two senior developers, who would print it and bring it to the Thursday review meeting. Then came the merge weekend, when four long-lived branches met for the first time and nobody went home before midnight.

You ask Maya who you should email for a review.

"Nobody," she says. "Push your branch and open a pull request. CI will build it, CODEOWNERS will ask the right people, and Copilot will leave comments before any of us look. If main is red or nobody approved, the merge button stays grey. Not because we're strict: because GitHub won't let it."

Tomás adds from the next desk: "And keep it small. If your PR is open longer than two days, it's two PRs."

Jonas Berg forwards you a link. A Dependabot pull request bumped the OpenTelemetry packages overnight, CI is already green, and it's waiting for one approval. "That's the other half of the job," he says. "The robots open PRs too. We review them like anyone else's."

In your notebook, under Habits I brought with me, you write: "Code review is a meeting." Then: "Merging is an event." You suspect both are about to be crossed out.

🏚️ Old way → 🚀 New way

🧠 GitHub flow: one main branch, many short ones

💡 main is always releasable. Every change reaches it through a pull request, and nothing else does.

GitHub flow is deliberately simple:

1. Branch from main with a descriptive name (fix/import-timeout, feat/price-alerts).
2. Commit small steps and push early. A pushed branch is backed up and visible.
3. Open a pull request, as a draft if you want feedback before it's finished.
4. CI runs and reviewers comment. You push fixes to the same branch, and the PR updates.
5. Merge when the checks are green and the required approvals are in. Delete the branch.
6. Deploy from main. At Ledgerly that happens automatically after CI passes on main (chapter 12).

There is no develop branch, no release/* branch and no merge weekend. Unfinished work either stays on its branch, or it's merged behind a feature flag (the alerts endpoint already does this, see chapter 19). The flag decides what users see. The branch decides nothing.

💻 In Ledgerly: what "merged to main" sets in motion

The CI workflow runs on every pull request and every push to main that touches the sample:

📄 .github/workflows/ci.yml

# CI: every push and pull request is built and tested. A red build blocks the merge (see branch protection, chapter 8).
name: ci

on:
  push:
    branches: [main]
    paths: ["sample/**", ".github/workflows/ci.yml"]
  pull_request:
    paths: ["sample/**", ".github/workflows/ci.yml"]
  workflow_dispatch:

The deploy workflow doesn't watch branches at all. It waits for CI to finish on main:

📄 .github/workflows/deploy.yml

on:
  workflow_run:
    workflows: [ci]
    types: [completed]
    branches: [main]
  workflow_dispatch:

So the only road to production is: pull request, green CI, merge, green CI on main, deploy. Chapter 9 walks through the CI file line by line, and chapter 12 does the same for deploy.

Issues, projects and commit messages

Work starts as an issue, not as an email. Elena writes the "CSV imports time out" issue with the user's words and a sample file. You link your PR to it, and the issue closes when the PR merges. A project board (Elena's has the columns Todo, In progress, In review and Done) shows the team's work without a status meeting. Leo uses the same board for frontend tasks, so the API change and the UI change sit next to each other.

Ledgerly writes commit messages and PR titles as conventional commits: a type, an optional scope and a short summary.

feat(imports): process CSV files in a background worker
fix(worker): complete duplicate messages instead of abandoning them
docs(readme): replace the setup wiki with aspire run
chore(deps): bump the opentelemetry group

The team squash-merges, so the PR title becomes the one commit on main. Scan git log --oneline and you can tell features from fixes from chores at a glance, and a tool can turn the history into release notes later.

🗺️ The life of a change

flowchart LR
    Issue["Issue<br/>CSV imports time out"] --> Branch["Branch<br/>fix/import-timeout"]
    Branch -- "push" --> PR["Pull request"]
    PR --> CI["CI checks<br/>build-test, containers, infra"]
    PR --> Scan["CodeQL<br/>analyze"]
    PR --> Review["Reviews<br/>Copilot, then CODEOWNERS"]
    CI --> Gate{"Ruleset on main<br/>all green and approved?"}
    Scan --> Gate
    Review --> Gate
    Gate -- "no" --> Branch
    Gate -- "yes, squash merge" --> Main["main"]
    Main -- "CI passes on main" --> Deploy["deploy.yml<br/>production environment"]

🧠 Protecting main: rulesets, required checks and environments

💡 A team rule that lives in a wiki is a suggestion. A team rule that lives in a ruleset is a fact.

GitHub has two ways to protect a branch. Classic branch protection rules are the older one. Rulesets are the newer mechanism, and the one to reach for today (About rulesets):

• 🔧 Availability: rulesets work on public repositories on GitHub Free, and on public and private repositories on Pro, Team and Enterprise Cloud. Organization-wide rulesets and push rulesets need Team or Enterprise.
• A repository can have up to 75 rulesets. They layer with each other and with classic branch protection, and when several apply, the most restrictive wins.
• Each ruleset has an enforcement status: Active, Evaluate (report what would have been blocked, without blocking) or Disabled. Evaluate is how you roll out a stricter rule without surprising the team.
• A bypass list names who may skip the rules, for example a release bot. Keep it short. Every name on it is a way around review.
• Anyone with read access can see the rulesets, so "what are the rules here?" has an answer you can look up.

The rules you can turn on include (Available rules for rulesets): require a pull request (with a number of approvals, review from code owners, and dismissing stale approvals when new commits arrive), require status checks to pass, require linear history, block force pushes, require signed commits, require deployments to succeed and require code scanning results.

Ledgerly's ruleset on main is short:

💻 In Ledgerly: where the check names come from

A required status check must have passed on the latest commit of the PR, and its name must match the job name exactly. The names come straight from the workflow files:

📄 .github/workflows/ci.yml

jobs:
  build-test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    # ...
  containers:
    runs-on: ubuntu-latest
    needs: build-test
    timeout-minutes: 20
    strategy:
      matrix:
        project: [Ledgerly.Api, Ledgerly.Worker, Ledgerly.MarketData, Ledgerly.MigrationService]
    # ...
  infra:
    runs-on: ubuntu-latest
    timeout-minutes: 10

📄 .github/workflows/codeql.yml

jobs:
  analyze:
    runs-on: ubuntu-latest
    timeout-minutes: 30

None of the jobs has a name:, so the job ID is the check name: build-test, infra and analyze. A matrix job reports one check per matrix value, so containers shows up four times, as containers (Ledgerly.Api), containers (Ledgerly.Worker) and so on. Rename a job, and the required check waits forever for a name that no longer reports. Change the workflow and the ruleset in the same PR.

Environments: the gate before production

Rulesets guard main. Environments guard deployments. Ledgerly's deploy job runs in an environment called production:

📄 .github/workflows/deploy.yml

    environment:
      name: production # protection rules (reviewers, branch filter) live on the environment
      url: ${{ steps.apps.outputs.apiUrl }}

An environment can require reviewers (up to 6 users or teams, and only one of them needs to approve, optionally never the person who triggered the run), a wait timer, deployment branch restrictions and custom protection rules. It also holds its own secrets and variables (Deployments and environments).

🔧 💰 Read the plan small print: on Free, Pro and Team plans, required reviewers and wait timers work only for public repositories. For a private repository you need Enterprise. Ledgerly's beta repo is private on Team, so the team relies on the main ruleset plus a branch filter on the environment, and Priya gets a notification for every deploy.

Tomás has one complaint about all of this: rulesets and environments are settings, not files, so they don't show up in a diff. "If it's not in git, it doesn't exist," he says, and writes the ruleset down as an ADR (the toolkit has adr-template.md) so the next person can see what was decided and why.

🧠 Reviews that find the right people: CODEOWNERS, templates and Copilot

💡 Let GitHub decide who reviews and what the author must say. Spend human attention on the design.

CODEOWNERS

A CODEOWNERS file maps paths to the people or teams who own them. When a PR touches a path, its owners are requested for review automatically. With the "require review from code owners" rule, their approval becomes mandatory (About code owners).

Two details matter:

• GitHub looks for the file in .github/CODEOWNERS, then CODEOWNERS at the root, then docs/CODEOWNERS, and uses the first one it finds.
• Inside the file, the last matching pattern wins. Put the broad rule first and the specific ones below it.

The sample repository doesn't contain a CODEOWNERS file. This is what Ledgerly's looks like:

# illustrative, not in the sample: .github/CODEOWNERS
# The last matching pattern wins, so the catch-all goes first.
*                                   @ledgerly/developers

# Infrastructure and pipelines: Tomás's team reviews every change.
/sample/infra/                      @ledgerly/platform
/.github/workflows/                 @ledgerly/platform

# Supply chain: package sources and versions need a security review.
/sample/nuget.config                @ledgerly/security
/sample/Directory.Packages.props    @ledgerly/security

# Schema changes are hard to undo: the tech lead looks at every migration.
/sample/src/Ledgerly.Core/Data/Migrations/   @maya-okafor

Use teams rather than individuals where you can, so a vacation doesn't block a merge. Note what the supply-chain lines mean: every Dependabot NuGet PR touches Directory.Packages.props, so Jonas's team approves each one. That's intended.

The pull request template

A pull request template pre-fills the description of every new PR, so the reviewer always gets the same questions answered. The sample doesn't include one, but the toolkit has pull_request_template.md ready to copy to .github/ (see the toolkit). Its shape:

<!-- illustrative, not in the sample: .github/pull_request_template.md -->
## What and why
Fixes #

## How I tested it
- [ ] Unit or integration tests added or updated
- [ ] Ran it locally with `aspire run`

## What happens when it fails?
<!-- Retries, timeouts, the dead-letter queue, rollback -->

## Checklist
- [ ] Database migration is backward compatible (old code still runs against the new schema)
- [ ] New settings are documented, and no secrets are in code or config
- [ ] Logs, metrics or traces added for the new path

The "What happens when it fails?" heading is Maya's. Every PR answers it before she has to ask.

Copilot code review and the Copilot cloud agent

Copilot code review reviews a pull request the way a teammate would: it leaves comments on the diff, often with a suggested change. You request it like any other reviewer, or make it automatic for a repository or organization through settings or a ruleset. Business and Enterprise organizations can enable it even for members who don't have a Copilot license, billed to the organization 💰 (Copilot on GitHub).

At Ledgerly, Copilot reviews first and humans second. It's good at the things people skim: a missing CancellationToken, a DbContext captured in a singleton, a null path nobody tested. Its comment is not an approval, and it doesn't count toward the ruleset. A person who understands the design still signs off.

🔧 The Copilot cloud agent (GitHub's docs renamed it from "Copilot coding agent") goes one step further. You assign an issue to Copilot, it works in an environment powered by GitHub Actions, and it opens a pull request for review. It's available on paid plans, and for Business and Enterprise an org admin has to enable it. Its PR goes through exactly the same gates as yours: CI, CODEOWNERS, a human approval. Chapter 20 covers how to write issues it can finish, and the .github/copilot-instructions.md file that teaches it Ledgerly's conventions.

🗺️ A pull request meets the gates

sequenceDiagram
    participant You as You
    participant GH as GitHub
    participant CI as Actions ci and codeql
    participant Bot as Copilot code review
    participant Owner as Code owner
    You->>GH: Push branch and open pull request
    GH->>CI: Start build-test, containers, infra, analyze
    GH->>Bot: Request automatic review
    GH->>Owner: Request review from CODEOWNERS
    Bot-->>GH: Comments and suggested changes
    CI-->>GH: build-test failed
    GH-->>You: Merge blocked by required checks
    You->>GH: Push a fix to the same branch
    GH->>CI: Run all checks again
    CI-->>GH: All checks passed
    Owner-->>GH: Approve
    GH-->>You: Ruleset satisfied, merge enabled

🧠 Supply chain on autopilot: Dependabot, CodeQL and secret scanning

💡 The safest dependency update is a small one that CI tested last week, not a big one somebody postponed for a year.

Dependabot version updates

Dependabot reads .github/dependabot.yml and opens pull requests when a newer version of a package or an action exists. Every one of those PRs runs CI like yours does, so "is this upgrade safe?" is answered by your tests, not by a hunch.

💻 In Ledgerly: grouped updates for NuGet and actions

📄 .github/dependabot.yml

# Dependabot opens pull requests for outdated packages and actions. CI tests every one of them.
version: 2
updates:
  - package-ecosystem: nuget
    directory: /sample
    schedule:
      interval: weekly
    groups:
      # One PR per family instead of twenty. Versions inside a family must move together.
      aspire:
        patterns: ["Aspire.*"]
      dotnet-platform:
        patterns: ["Microsoft.AspNetCore.*", "Microsoft.EntityFrameworkCore*", "Microsoft.Extensions.*"]
      opentelemetry:
        patterns: ["OpenTelemetry*", "Azure.Monitor.OpenTelemetry*"]
      testing:
        patterns: ["xunit*", "Microsoft.Testing.*", "Testcontainers*"]

  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    groups:
      actions:
        patterns: ["*"]

Read it top to bottom:

• Two ecosystems. nuget looks in /sample, where the solution and Directory.Packages.props live. github-actions looks at /, which means the workflows in .github/workflows. Dependabot understands Central Package Management, so it edits the one PackageVersion line instead of every project file.
• Groups. Without them you'd get one PR per package: six Aspire PRs that must all merge together anyway. With them you get one PR per family. Groups match by patterns, and can also be limited with update-types: [minor, patch] if you want majors to arrive alone.
• Weekly. schedule.interval also accepts daily, monthly, quarterly, semiannually, yearly and cron. Weekly is a rhythm a small team can keep.
• 🔧 Cooldown. Version updates have a default cooldown of 3 days: a new release isn't proposed until it's 3 days old. That gives the ecosystem time to discover a broken release before it reaches you.

Two more ecosystems worth knowing: dotnet-sdk updates the SDK version in global.json, and docker updates base images in Dockerfiles (Ledgerly has none, see chapter 9) (Dependabot options reference).

Dependabot is half of the supply-chain story. The other half runs at build time: NuGet audit fails the build when a package has a known vulnerability, which is exactly what happened while building the sample (chapter 9).

CodeQL code scanning

CodeQL is GitHub's static analysis engine. It looks for security bugs (SQL injection, path traversal, unsafe deserialization) and reports them under Security → Code scanning and as comments on the pull request (Configuring code scanning).

💻 In Ledgerly: the CodeQL workflow

📄 .github/workflows/codeql.yml

# Static security analysis (SAST). Findings show up under Security > Code scanning and on pull requests.
name: codeql

on:
  push:
    branches: [main]
    paths: ["sample/**"]
  pull_request:
    paths: ["sample/**"]
  schedule:
    - cron: "17 3 * * 1" # weekly, catches new queries against unchanged code

permissions:
  contents: read
  security-events: write

jobs:
  analyze:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
      - uses: github/codeql-action/init@v4
        with:
          languages: csharp
          build-mode: none # no build needed for C#, analysis reads the source
      - uses: github/codeql-action/analyze@v4

Three choices stand out:

• build-mode: none. For C#, CodeQL can analyze the source without compiling it (the other modes are autobuild and manual). It's faster, and a broken build can't hide a finding.
• The weekly schedule. The queries improve over time, so every Monday at 03:17 UTC the same code gets checked against the new queries, even if nobody pushed.
• security-events: write. That's the one extra permission the workflow needs, to upload its results. Everything else stays read-only.

This is the advanced setup: a workflow file you control. The default setup is a one-click setting with no file at all, and for C# it also uses build-mode: none. It scans pushes to the default branch, pull requests and weekly. 🔧 💰 CodeQL is free for public repositories. Private and internal repositories in an organization need GitHub Code Security, sold separately since 2025.

Secret scanning and push protection

Secret scanning finds credentials committed to the repository, and push protection blocks a push that contains one before it ever reaches GitHub. Both are free and automatic for public repositories, where push protection for users is on by default. 🔧 For private repositories and repo-level push protection you need GitHub Secret Protection (About push protection).

Ledgerly's best defense is having almost nothing to leak: no SAS keys (chapter 7), no deployment secrets thanks to OIDC (chapter 12), and managed identities everywhere (chapter 13). Jonas still turns push protection on, because a developer's personal token in a test script is enough to ruin a week.

⚠️ Common traps

🧰 Helpers

The pull request loop from the terminal, with the GitHub CLI:

git switch -c fix/import-timeout          # branch from an up-to-date main
git commit -am "fix(imports): move CSV processing to the worker"
git push -u origin HEAD
gh pr create --fill                       # title and body from your commits
gh pr checks --watch                      # wait for CI and CodeQL
gh pr view --web                          # read the review comments
gh pr merge --squash --delete-branch      # when the ruleset allows it

Reviewing someone else's PR locally:

gh pr list                                # open PRs in this repo
gh pr checkout 42                         # check out PR #42 as a local branch
cd sample
dotnet test --solution Ledgerly.slnx      # run the tests yourself

A conventional commit cheat sheet: feat (a new feature), fix (a bug fix), docs, test, refactor (no behavior change), ci (workflows), chore (dependencies, tooling). Add a scope in parentheses when it helps: fix(worker): ....

Make it permanent:

• Copy the toolkit's pull_request_template.md to .github/ and dependabot.yml to .github/, then adjust the directory and groups (toolkit).
• Add a CODEOWNERS file with teams, not individuals, and turn on "require review from code owners" in the main ruleset.
• Create the ruleset in Evaluate mode first, watch a week of PRs, then switch it to Active. Record it in an ADR.
• Turn on Copilot code review as automatic for the repository, and add the toolkit's copilot-instructions.md so its comments follow your conventions.
• Use the toolkit's pr-review-checklist.md when you review. New terms are in the glossary.

🧪 Try it yourself (optional, ~25 min)

1. Fork the course repository and clone your fork, then make your fork the default for gh: bash gh repo fork vygantas-meskauskis/cloud-native-dotnet --clone cd cloud-native-dotnet gh repo set-default Pick your fork when gh repo set-default asks. On GitHub, open your fork's Actions tab and enable workflows if GitHub asks you to.
2. Create a branch and make a small change under sample/ so CI runs, for example improve a comment in sample/src/Ledgerly.Worker/AlertEvaluator.cs: bash git switch -c docs/alert-evaluator-comment git commit -am "docs(worker): explain why alerts need a single replica" git push -u origin HEAD
3. Open the pull request against your fork and watch the checks: bash gh pr create --fill gh pr checks --watch Note the check names: build-test, containers (Ledgerly.Api) and its siblings, infra, analyze.
4. In your fork, go to Settings → Rules → Rulesets and create a branch ruleset for the default branch. Require a pull request and the build-test status check, block force pushes, and set enforcement to Evaluate. (Your fork is public, so rulesets work on the Free plan 🔧.)
5. Push another commit to the PR. Then open Settings → Rules → Insights and see what the ruleset would have blocked, without anything being blocked.
6. If your plan includes Copilot code review, add Copilot as a reviewer on the PR and read its comments. Decide which ones you'd accept.
7. Add an illustrative .github/CODEOWNERS with yourself as the owner of /sample/infra/, open a second PR that touches a Bicep comment, and watch GitHub request your review automatically.
8. Merge with gh pr merge --squash --delete-branch and run git log --oneline on main: one commit, with your conventional title.

✅ Recap

1. GitHub flow keeps main releasable: short branches, pull requests for every change, and deployment only after CI passes on main.
2. Rulesets, required status checks, CODEOWNERS and environments turn the team's rules into settings GitHub enforces, so nothing depends on someone remembering.
3. Dependabot, CodeQL, secret scanning and Copilot code review run on every PR, and humans still give the approval.

Next → Chapter 9: CI with GitHub Actions

Chapter 9: CI with GitHub Actions

⏱ About 35 min · You'll learn: how Ledgerly's CI workflow builds, tests, packages and lints every pull request on a fresh machine, why it runs the same commands you run locally, how container images get built without a Dockerfile, and the real failures that shaped the workflow.

📖 Story: Green on my machine, red in CI

Your first week includes a turn on "CI duty", and Tomás starts it by opening the run history. He scrolls back a month to a red cross next to build-test on a pull request from Leo, and opens the log:

error NU1903: Package 'System.Security.Cryptography.Pkcs' 10.0.12 has a known high severity vulnerability

"Leo's laptop was green," Tomás says. "He hadn't touched a package. CI was red anyway, and CI was right. It's the only machine that counts. Your laptop has a warm cache, an SDK you installed in March and a bin folder full of history. The runner starts from nothing, every time."

The cause was a package nobody referenced directly, pulled in by another one, with a newly published vulnerability. NuGet audit flagged it, and because warnings are errors at Ledgerly, the build stopped. One line in Directory.Packages.props pinned the patched version. Then Priya tells you about the week the team moved to the .NET 10 SDK and dotnet test refused to run at all.

At Nordbank Insurance, "the build" was BUILD01, a tower PC under a desk in the server room. Somebody installed SDKs on it by hand, a scheduled batch file ran every night, and when it broke, the person who knew the batch file was on holiday. In your notebook, under Habits I brought with me, you write: "The build server is a pet." You don't need a question mark this time.

🏚️ Old way → 🚀 New way

🧠 Anatomy of a workflow

💡 A workflow is a file that answers four questions: when does it run, with which permissions, in what order, and where.

GitHub Actions runs workflows (YAML files in .github/workflows). A workflow has triggers (on:), one or more jobs that each run on a fresh runner machine, and steps inside each job that either run a shell command (run:) or call a reusable action (uses:). Jobs run in parallel unless one needs another.

💻 In Ledgerly: the top of ci.yml

📄 .github/workflows/ci.yml

# CI: every push and pull request is built and tested. A red build blocks the merge (see branch protection, chapter 8).
name: ci

on:
  push:
    branches: [main]
    paths: ["sample/**", ".github/workflows/ci.yml"]
  pull_request:
    paths: ["sample/**", ".github/workflows/ci.yml"]
  workflow_dispatch:

# Least privilege: this workflow only reads the repo.
permissions:
  contents: read

# A new push to the same branch cancels the run that is now outdated.
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

defaults:
  run:
    working-directory: sample

env:
  DOTNET_NOLOGO: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true

Line by line:

• on: CI runs on pushes to main, on every pull request, and by hand (workflow_dispatch, which is what gh workflow run ci uses). The paths filter skips CI when a change touches neither the sample nor the workflow itself. The course text in chapters/ changes often, and none of it needs a .NET build. Note that the workflow file is in its own filter: a change to CI must run CI.
• permissions: Every run gets a short-lived GITHUB_TOKEN. This block says that token can only read the repository. A step that's compromised (a malicious package in a restore, a hijacked action) can't push code, open releases or change settings. Set it at the top of every workflow and widen it per job only when needed, like CodeQL's security-events: write in chapter 8.
• concurrency: Runs in the same group queue up, and cancel-in-progress: true cancels the older one. Push three fixes in a row, and only the last one keeps a runner busy. github.ref makes the group per branch, so your PR never cancels someone else's (Control workflow concurrency). Deployments use the opposite setting, as you'll see below.
• defaults.run.working-directory: sample. Every run: step starts in sample/, so commands look exactly like the ones in the README. It applies only to run: steps, which is why paths given to actions (sample/global.json, sample/TestResults/) still include the folder.
• env: Two variables turn off the .NET welcome banner and CLI telemetry. Less noise in the log.

Compare the deploy workflow's concurrency block:

📄 .github/workflows/deploy.yml

# Never run two deployments at once, and never cancel one halfway.
concurrency:
  group: deploy-production
  cancel-in-progress: false

Cancelling an outdated build is free. Cancelling a deployment halfway leaves production in a state nobody tested. One fixed group name, no cancellation: deployments wait in line (chapter 12).

🧠 The build-test job: the commands you already know

💡 CI should run the same commands you run locally. If the workflow needs a trick your laptop doesn't, one of them is lying.

💻 In Ledgerly: build-test

📄 .github/workflows/ci.yml

  build-test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-dotnet@v6
        with:
          global-json-file: sample/global.json

      - name: Restore
        run: dotnet restore Ledgerly.slnx

      # Warnings are errors, analyzers + code style run, NuGet audit fails on vulnerable packages.
      - name: Build
        run: dotnet build Ledgerly.slnx -c Release --no-restore

      # Integration tests start a throwaway SQL Server container with Testcontainers (Docker is on the runner).
      - name: Test
        run: >
          dotnet test --solution Ledgerly.slnx -c Release --no-build
          --coverage --coverage-output-format cobertura
          --report-xunit-trx

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: test-results
          path: sample/TestResults/
          retention-days: 14

The steps, in order:

1. actions/checkout@v7 clones the commit under test.
2. actions/setup-dotnet@v6 installs the SDK. Instead of a version number in YAML, it reads global.json, the same file your local dotnet reads. Upgrade the SDK in one place and both follow.
3. Restore, then Build with --no-restore, then Test with --no-build. Three steps instead of one so the log shows exactly which phase failed, and nothing is done twice.
4. timeout-minutes: 20. A hung test (a container that never starts) fails after 20 minutes instead of burning runner time for hours.
5. if: always() on the upload. Without it, a failed test step skips every later step, and you lose the results exactly when you need them.

The > after run: is YAML's folded style: the three lines become one command, which keeps a long command readable.

The SDK pin itself:

📄 sample/global.json

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

rollForward: latestFeature means "10.0.100 or any newer 10.0 SDK", so a patched SDK on the runner is used without a commit. The test section is the second real lesson below.

Lesson 1: NuGet audit failed the build

The Build step's comment promises that warnings are errors and NuGet audit fails on vulnerable packages. Both come from the repo-wide build settings (chapter 3):

📄 sample/Directory.Build.props

    <!-- Quality gates: warnings fail the build, analyzers and code style run in every build (also in CI). -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>

NuGet audit checks every package in the graph during restore, including the ones you never referenced yourself. While the sample was being built, a transitive dependency, System.Security.Cryptography.Pkcs (versions 9.0.11 and 10.0.12 came in through other packages), had known vulnerabilities: NU1902 (moderate) and NU1903 (high). With TreatWarningsAsErrors, those warnings stopped the build.

The tempting fix is to turn audit off or downgrade the warning. The right fix is to pin the patched version with Central Package Management's transitive pinning:

📄 sample/Directory.Packages.props

  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <!-- Lets a PackageVersion below also override a TRANSITIVE dependency (used for security patches). -->
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup Label="Security pins for transitive dependencies (NuGet audit, NU1902/NU1903)">
    <PackageVersion Include="System.Security.Cryptography.Pkcs" Version="10.0.14" />
  </ItemGroup>

The label says why the pin exists, so whoever removes it later (when the parent packages ship the fix) knows what to check. This is why a red build with no code change is a feature: the vulnerability was found by a robot during a pull request, not by an attacker.

Lesson 2: VSTest is gone, Microsoft.Testing.Platform is in

The second failure happened when the team moved to the .NET 10 SDK with xUnit v3 4.x. dotnet test stopped with:

Testing with VSTest target is no longer supported by Microsoft.Testing.Platform on .NET 10 SDK

Some background. dotnet test now has two modes. VSTest mode is the old one and still the default. Microsoft.Testing.Platform (MTP) mode is new in the .NET 10 SDK: the test runner is embedded in the test project, which is an executable. xUnit v3 supports MTP natively, and running MTP test projects through the VSTest bridge is now legacy (MTP v2 drops it on the .NET 10 SDK).

The fix had three parts:

1. Opt in to MTP with "test": { "runner": "Microsoft.Testing.Platform" } in global.json (above).
2. Use the new command line: dotnet test --solution Ledgerly.slnx. In MTP mode the solution is passed with --solution.
3. Drop the VSTest packages. Microsoft.NET.Test.Sdk, xunit.runner.visualstudio and coverlet.collector were removed. Coverage now comes from Microsoft.Testing.Extensions.CodeCoverage, which provides --coverage:

📄 sample/tests/Ledgerly.UnitTests/Ledgerly.UnitTests.csproj

  <PropertyGroup>
    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
    <OutputType>Exe</OutputType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="xunit.v3" />
    <PackageReference Include="Microsoft.Testing.Extensions.CodeCoverage" />
    <PackageReference Include="Microsoft.Extensions.TimeProvider.Testing" />
  </ItemGroup>

In the Test step, --coverage --coverage-output-format cobertura writes a Cobertura coverage file, and --report-xunit-trx writes xUnit's TRX results file. The suite has 23 tests: 15 unit tests and 8 integration tests against a real SQL Server that Testcontainers starts on the runner (Docker is already installed there). Locally, the integration tests skip themselves when no SQL Server is available (chapter 17).

One more MTP detail bit the team: when zero tests run, MTP returns exit code 8, and CI fails. That's usually right, because a filter that matches nothing or a project that isn't discovered should be loud. If a run with no tests is genuinely expected, MTP's --ignore-exit-code 8 says so explicitly.

Test results without a test UI

GitHub Actions has no built-in test results page beyond job summaries and artifacts. You have three options: upload the TRX files with actions/upload-artifact (what Ledgerly does), write a Markdown summary to $GITHUB_STEP_SUMMARY, or use a community action that renders TRX files as a check. The artifact keeps the evidence for retention-days: 14, long enough to investigate a flaky test without paying to store every run forever 💰.

🗺️ What one pull request runs

flowchart LR
    PR["Pull request<br/>touches sample/**"] --> BT["build-test<br/>restore, build, test"]
    PR --> Infra["infra<br/>bicep lint and build"]
    PR --> CQ["analyze<br/>codeql.yml"]
    BT -- "needs" --> C1["containers<br/>Ledgerly.Api"]
    BT -- "needs" --> C2["containers<br/>Ledgerly.Worker"]
    BT -- "needs" --> C3["containers<br/>Ledgerly.MarketData"]
    BT -- "needs" --> C4["containers<br/>Ledgerly.MigrationService"]
    BT -- "always" --> Art["Artifact<br/>test-results, 14 days"]
    C1 --> Checks["Required status checks<br/>ruleset on main"]
    C2 --> Checks
    C3 --> Checks
    C4 --> Checks
    Infra --> Checks
    CQ --> Checks

build-test, infra and analyze start in parallel on separate runners. The four containers jobs wait for build-test, because there's no point packaging code whose tests fail.

🧠 Container images without a Dockerfile

💡 The .NET SDK knows your app better than a Dockerfile does. Let it build the image.

The .NET SDK can build an OCI container image directly: dotnet publish with the PublishContainer target. No Dockerfile, no docker build. Without a registry it loads the image into the local Docker or Podman daemon. With -p:ContainerRegistry=... it pushes straight to a registry such as Azure Container Registry (SDK container publishing). Aspire and azd use the same mechanism for .NET projects.

💻 In Ledgerly: the containers matrix

📄 .github/workflows/ci.yml

  # Proves the deployable images build. Pushing happens only in deploy.yml.
  containers:
    runs-on: ubuntu-latest
    needs: build-test
    timeout-minutes: 20
    strategy:
      matrix:
        project: [Ledgerly.Api, Ledgerly.Worker, Ledgerly.MarketData, Ledgerly.MigrationService]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-dotnet@v6
        with:
          global-json-file: sample/global.json
      - name: Build container image (no Dockerfile needed)
        run: dotnet publish src/${{ matrix.project }} -c Release /t:PublishContainer -p:ContainerImageTag=ci-${{ github.sha }}

A matrix turns one job definition into one job per value: four projects, four parallel jobs, four checks. Each image is tagged ci-<commit SHA>, so you can tell exactly which commit produced it. The image name comes from the project file:

📄 sample/src/Ledgerly.Api/Ledgerly.Api.csproj

  <PropertyGroup>
    <UserSecretsId>ledgerly-api-6f1d2c</UserSecretsId>
    <!-- SDK container support: `dotnet publish /t:PublishContainer` builds an image without a Dockerfile. -->
    <ContainerRepository>ledgerly-api</ContainerRepository>
  </PropertyGroup>

The other three set ledgerly-worker, ledgerly-marketdata and ledgerly-migrations. Without ContainerRepository, the name would default to the assembly name.

CI builds the images but never pushes them: it has no registry credentials and only contents: read. The deploy workflow runs the same command with a registry, after signing in to Azure with OIDC:

📄 .github/workflows/deploy.yml

          for project in Ledgerly.Api Ledgerly.Worker Ledgerly.MarketData Ledgerly.MigrationService; do
            dotnet publish "src/$project" -c Release /t:PublishContainer \
              -p:ContainerRegistry="$LOGIN_SERVER" -p:ContainerImageTag="$SHA"
          done

What you get for free

The SDK makes choices that a hand-written Dockerfile often gets wrong:

• A current base image. For .NET 10 the default distro is Ubuntu 24.04 (Noble). The images Ledgerly built this way were roughly 120 MB compressed for the default ASP.NET image (illustrative: yours will differ).
• A non-root user. Since .NET 8, the Linux images include a non-root user called app. A container escape lands in an unprivileged account.
• Port 8080, not 80. The default ASP.NET Core port in containers is 8080 (it was 80 before .NET 8), configured through ASPNETCORE_HTTP_PORTS. That's why every probe and ingress in Ledgerly's Container Apps points at 8080:

📄 sample/infra/modules/apps.bicep

var probes = [
  {
    type: 'Startup'
    httpGet: { path: '/alive', port: 8080 }
    // ...
  }
  // ...
]

Going smaller: chiseled images

Chiseled images (Ubuntu's distroless flavor) have no shell, no package manager, run non-root by default and contain only the packages the runtime needs. Less inside the image means fewer CVEs to patch. You choose them with ContainerFamily, which is appended to the tag (noble-chiseled gives mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled):

<!-- illustrative, not in the sample: smaller, shell-less base images -->
<PropertyGroup>
  <ContainerFamily>noble-chiseled-extra</ContainerFamily>
</PropertyGroup>

Plain chiseled images have no ICU (globalization) or time zone data, so culture-aware formatting and time zone conversions stop behaving like they do on your laptop. Ledgerly would use the -extra variant, which adds both. The alternative is InvariantGlobalization=true, which is only right for apps that never need culture-specific behavior. 🔧 And no shell means no docker exec ... bash for debugging, which is exactly the point.

One escaping trap: to set several tags, use ContainerImageTags (plural), which takes a semicolon-separated list. In a shell, an unquoted semicolon ends the command, so quote the value carefully (Container publish configuration).

🧠 Infrastructure is code, so CI lints it

💡 Bicep is a compiler. Use it on every pull request, not just on deployment day.

💻 In Ledgerly: the infra job

📄 .github/workflows/ci.yml

  # Infrastructure is code, so it gets linted like code. (Deploying it happens in deploy.yml.)
  infra:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - name: Lint and build Bicep
        run: |
          az bicep install
          az bicep lint --file infra/main.bicep
          az bicep build --file infra/main.bicep --stdout > /dev/null
          az bicep build-params --file infra/main.bicepparam --stdout > /dev/null

The job needs no Azure login: linting and compiling are local operations, so it runs with the same read-only token as everything else. lint applies the linter rules, build compiles main.bicep and all its modules to an ARM template (thrown away with > /dev/null, since only success matters), and build-params checks that main.bicepparam matches the template's parameters.

This job exists because of a real lesson. While writing the infrastructure, the Bicep compiler caught two mistakes before Azure did:

• BCP138: a for expression inside concat() in a property, which Bicep doesn't allow. The fix was to move it to a variable.
• BCP037: identity wasn't a known property on a KEDA scale rule for API version 2024-03-01. The fix was the newer 2025-01-01 API version.

Neither needed a subscription to find. Chapter 11 goes through the Bicep itself.

🗺️ From push to green

sequenceDiagram
    participant Dev as You
    participant GH as GitHub
    participant R as Runners
    participant RS as Ruleset on main
    Dev->>GH: Push commit A to the PR branch
    GH->>R: Start ci run for commit A
    Dev->>GH: Push commit B a minute later
    GH->>R: Cancel run A, same concurrency group
    GH->>R: Start ci run for commit B
    R->>R: build-test, infra and analyze in parallel
    R->>R: containers matrix after build-test
    R-->>GH: Upload test-results artifact
    R-->>GH: Report checks for commit B
    GH->>RS: Are all required checks green on the latest commit
    RS-->>Dev: Merge allowed after approval

🧠 Keeping CI fast, current and trustworthy

💡 Your workflow runs third-party code with access to your repository. Treat it like a dependency, because it is one.

Action versions and pinning

Every uses: line runs code someone else wrote. Ledgerly uses these versions 🔧:

These are major version tags: @v7 moves to each new 7.x release. You get fixes without editing the file, and you trust the publisher not to break or compromise the tag. The alternative is pinning to a full commit SHA, which can never change under you, at the price of less readable files and more update PRs. There's no single right answer. A common split is major tags for actions published by GitHub and Microsoft, and SHA pins for smaller third-party actions. Never use a branch ref like @master: for azure/login, branch refs aren't supported at all.

Either way, Dependabot keeps them current. The github-actions ecosystem in .github/dependabot.yml (chapter 8) groups every action update into one weekly PR, and CI tests it like any other change.

Caching and lock files

The sample doesn't cache NuGet packages, and RestorePackagesWithLockFile is false in Directory.Build.props. On a fresh runner, restore downloads everything each time. For a solution this size that's a small part of the run, and it keeps the workflow simple. If restore time grows, measure first, then add a cache. A cache needs a stable key, which is the usual reason teams turn on NuGet lock files (packages.lock.json) at the same moment. Treat it as an optimization you add with numbers, not a default.

The rest of the safety net

• CodeQL runs as its own workflow on every PR (chapter 8), so CI doesn't need a security step.
• Required status checks turn this workflow into a gate. Without them, a red CI is just a red icon next to a merged PR (chapter 8 shows the exact check names).
• Least privilege at the top of every workflow. ci.yml reads, codeql.yml adds security-events: write, and only deploy.yml asks for id-token: write to get an OIDC token (chapter 12).

⚠️ Common traps

🧰 Helpers

Run what CI runs, from your machine:

cd sample
dotnet restore Ledgerly.slnx
dotnet build Ledgerly.slnx -c Release --no-restore
dotnet test --solution Ledgerly.slnx -c Release --no-build --coverage --coverage-output-format cobertura --report-xunit-trx
dotnet publish src/Ledgerly.Api -c Release /t:PublishContainer -p:ContainerImageTag=local

Watch and debug runs with the GitHub CLI:

gh workflow run ci                 # start CI by hand (workflow_dispatch)
gh run list --workflow ci          # recent runs
gh run watch                       # follow a run live
gh run view --log-failed           # only the logs of failed steps
gh run download <run-id> -n test-results   # get the TRX and coverage files
gh pr checks                       # check status for the current PR

A job summary, for when the artifact is too far away:

# illustrative, not in the sample: a one-line summary on the run page
      - name: Summary
        if: always()
        run: echo "Tests finished for commit ${{ github.sha }}. Results are in the test-results artifact." >> "$GITHUB_STEP_SUMMARY"

Make it permanent:

• Start new repositories from the toolkit's ci.yml and dependabot.yml (toolkit). Change the paths, the solution name and the matrix, and keep the permissions, concurrency and if: always() lines.
• Keep global.json as the single source of the SDK version, for your machine and for setup-dotnet.
• Make build-test, every containers (...) check, infra and analyze required in the main ruleset (chapter 8).
• Add a "CI is red" section to your runbook (the toolkit has runbook-template.md): gh run view --log-failed first, then reproduce locally with the commands above. Terms are in the glossary.

🧪 Try it yourself (optional, ~30 min)

1. Run the CI commands locally, in order: bash cd sample dotnet restore Ledgerly.slnx dotnet build Ledgerly.slnx -c Release --no-restore dotnet test --solution Ledgerly.slnx -c Release --no-build --coverage --coverage-output-format cobertura --report-xunit-trx With Docker running, all 23 tests run. Without it, notice which integration tests skip.
2. Build a container image without a Dockerfile: bash dotnet publish src/Ledgerly.Api -c Release /t:PublishContainer -p:ContainerImageTag=local docker image inspect ledgerly-api:local In the output, find the user (Config.User) and the exposed port (Config.ExposedPorts). Compare them with the probes in apps.bicep.
3. In your fork from chapter 8, start CI by hand and follow it: bash gh workflow run ci gh run watch
4. Break a test on purpose (change an expected value in a unit test), push to a PR branch, and read the failure with gh run view --log-failed. Download the test-results artifact and open the TRX file.
5. Push two commits quickly to the same branch. In the Actions tab, watch the first run get cancelled by the concurrency group.
6. Edit only a file under chapters/ in a separate branch and open a PR. CI doesn't start, because of the paths filter. If you made build-test a required check in chapter 8, notice that the PR now waits for a check that will never run.
7. Revert the broken test and watch the PR turn green.

✅ Recap

1. Ledgerly's CI runs the same restore, build and test commands you run locally, on a fresh runner, with least-privilege permissions and cancellation of outdated runs.
2. Real failures shaped it: NuGet audit stopped a vulnerable transitive package, the .NET 10 SDK required Microsoft.Testing.Platform, and Bicep lint catches infrastructure mistakes before Azure does.
3. The SDK builds secure, non-root container images on port 8080 without a Dockerfile, and CI proves every image builds before deploy ever pushes one.

Next → Chapter 10: Choosing Azure services

Chapter 10: Choosing Azure services

⏱ About 30 min · You'll learn: how to choose compute, data, messaging, caching, secrets and observability services on Azure with decision tables, why Ledgerly runs on Azure Container Apps, and which cost drivers actually move the monthly bill.

📖 Story: The Azure menu

Elena Rossi walks into standup with a spreadsheet open on her laptop. "The beta opens in eight weeks. Finance wants to know what it costs per month. I don't need a number to the cent. I need a range, and I need to know what makes it go up."

Maya Okafor books the small meeting room for an hour and writes AZURE MENU across the top of the whiteboard. "Azure has a couple of hundred services. We need six kinds." She draws six columns: compute, data, messaging, caching, secrets, observability. "For each column we pick one dish, write down why, and write down what makes it expensive. Elena gets cost drivers, not a guess."

You open your notebook. At Nordbank Insurance, choosing infrastructure meant a ticket, a three-week wait and a VM sized for the one busy week in January. Under Habits I brought with me you write: "Size for peak, then forget about it."

The numbers in this chapter's story (weeks, users, percentages) are illustrative. The service limits and free grants are real and marked 🔧.

🏚️ Old way → 🚀 New way

💡 In the cloud, the size of the bill is decided by your architecture choices, not by a hardware order.

🧠 How the menu is organized

Before choosing dishes, learn how the menu is laid out. Four concepts decide where a resource lives, who can touch it and who pays for it.

Pick a region close to your users and keep every service in it, so calls between them stay short (not every SKU exists in every region, so check before you commit). Put tags in code so they can't be forgotten: cost analysis can group by them (cost management).

💻 In Ledgerly: one region, one name, one set of tags

📄 sample/infra/main.bicep

param location string = resourceGroup().location
// ...
var name = '${appName}-${take(uniqueString(resourceGroup().id), 6)}'
var tags = {
  app: appName
  'managed-by': 'bicep'
}

• location defaults to the resource group's region, so you choose the region once, when you create the group.
• uniqueString(resourceGroup().id) is deterministic: the same resource group always gives the same six characters. Names like sql-ledgerly-ab12cd are unique across Azure but stable across deployments.
• Every module receives tags, so every resource can be found in cost analysis with app = ledgerly. Chapter 11 walks through the whole file.

💡 A resource group is a lifecycle boundary: choose its contents by asking "would I delete these together?"

🧠 Compute: where your code runs

This is the biggest decision on the menu, and the one with the most opinions attached. Microsoft publishes a comparison of its container and compute options (compare options). Here it is as a decision table.

Sources: compare options and Flex Consumption plan.

Why Ledgerly chose Container Apps

Maya writes the requirements on the left of the board and the matching ACA feature on the right. The result becomes an ADR (use the ADR template from the toolkit).

The trade-off Maya writes underneath: cold starts. A service scaled to zero takes a moment to wake up. The sample makes it a parameter (apiMinReplicas) so you can change your mind without changing code (overview, scaling).

💻 In Ledgerly: one environment, the serverless profile

📄 sample/infra/modules/environment.bicep

resource environment 'Microsoft.App/managedEnvironments@2025-01-01' = {
  name: 'cae-${name}'
  location: location
  tags: tags
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      // ...
    }
    workloadProfiles: [
      { name: 'Consumption', workloadProfileType: 'Consumption' } // 💰 serverless, pay per use, free monthly grant
    ]
  }
}

The environment is the shared boundary: one network and one Log Analytics workspace for all apps and jobs inside it. Think of it as the IIS server farm, except that you never see the servers. The Consumption workload profile is the serverless option; Dedicated profiles reserve hardware when you need it.

💡 Choose the platform that matches the shape of your work: one web app, many event handlers, or a handful of services, workers and jobs.

🗺️ Picking compute in four questions

flowchart TB
    Start["A new service"] --> K8s{"Do you need the<br/>Kubernetes API itself?"}
    K8s -- "yes" --> AKS["AKS<br/>Standard or Automatic"]
    K8s -- "no" --> Shape{"What shape<br/>is the work?"}
    Shape -- "one web app,<br/>IIS-like" --> AppSvc["App Service"]
    Shape -- "small event<br/>handlers" --> Func["Functions<br/>Flex Consumption"]
    Shape -- "APIs, workers<br/>and jobs" --> ACA["Container Apps"]
    ACA --> Idle{"Idle for<br/>long periods?"}
    Idle -- "yes" --> Zero["min replicas 0<br/>accept cold starts"]
    Idle -- "no, or must<br/>poll on a timer" --> One["min replicas 1"]

🧠 Data, messaging and caching

Data: Azure SQL Database, serverless

Your SQL Server knowledge transfers directly, which is the main reason Ledgerly didn't look further. The interesting decision is the purchasing model.

Sources: serverless tier, free offer, Entra-only authentication. Serverless fits low or bursty traffic. A database that is busy around the clock is more predictable on a provisioned tier.

📄 sample/infra/modules/sql.bicep

  sku: {
    name: 'GP_S_Gen5_2'
    tier: 'GeneralPurpose'
    family: 'Gen5'
    capacity: 2
  }
  properties: {
    autoPauseDelay: 60
    minCapacity: json('0.5')
    useFreeLimit: useFreeLimit // 💰 100,000 vCore-seconds per month, then pause until next month
    freeLimitExhaustionBehavior: useFreeLimit ? 'AutoPause' : null
  }

GP_S_Gen5_2 reads as General Purpose, Serverless, Gen5, max 2 vCores. Elena spots the catch: "Pause until next month means the beta is down until next month?" Yes. Fine for learning, bad once real users depend on it, so Maya adds a launch-checklist item: set sqlUseFreeLimit = false before the public beta. The migration service already copes with resume delays: "The execution strategy retries transient failures (e.g. Azure SQL serverless waking up)."

Messaging: Azure Service Bus tiers

Chapter 7 built the import pipeline on a queue. Here is how to pick the tier.

Source: Service Bus Premium and tiers.

Ledgerly's outbox relay sets MessageId to the outbox row id, and the queue drops any message with an id it has seen in the last ten minutes (duplicate detection). That one feature rules out Basic. Nothing in the beta needs dedicated capacity, private networking or 100 MB messages, which rules out Premium for now. Standard it is.

📄 sample/infra/modules/servicebus.bicep

// Service Bus Standard (needed for duplicate detection). Local (SAS key) auth is disabled:
// only Entra identities with a data role can send or receive.
// ...
  sku: { name: 'Standard', tier: 'Standard' }
  properties: {
    disableLocalAuth: true
    minimumTlsVersion: '1.2'
  }

Duplicate detection is configured on the entity when it is created, so this is a decision you want right on day one.

Caching: HybridCache first, Azure Managed Redis when you need it

Two facts shape this decision.

First, Azure Cache for Redis is being retired 🔧 (retirement FAQ):

New instance creation is being restricted before those dates. Don't start new work on it, even if a blog post from 2023 tells you to.

Second, the replacement is Azure Managed Redis 🔧 (overview). It is built on Redis Enterprise, comes in Memory Optimized, Balanced, Compute Optimized and Flash Optimized SKUs, is clustered by default (a non-clustered option exists up to 25 GB), is zone-redundant by default and supports Microsoft Entra ID authentication. StackExchange.Redis works with it without special cluster configuration.

But the first question isn't "which Redis?" It's "do we need a shared cache at all?"

💻 In Ledgerly: Redis is optional by design

📄 sample/src/Ledgerly.Api/Program.cs

// ── Caching: HybridCache (in-memory L1). Redis becomes the shared L2 when a "cache" connection exists.
if (!string.IsNullOrEmpty(builder.Configuration.GetConnectionString("cache")))
{
    builder.AddRedisDistributedCache("cache");
}

builder.Services.AddHybridCache(options => options.DefaultEntryOptions = new HybridCacheEntryOptions
{
    Expiration = TimeSpan.FromSeconds(30),
    LocalCacheExpiration = TimeSpan.FromSeconds(10),
});

The code doesn't care which mode it runs in. Locally, Aspire starts a Redis container and passes a cache connection string, so you get both levels. In Azure, enableRedis defaults to false in main.bicep: the API uses memory only, and prices are cached for 30 seconds per replica. If the beta grows, you flip one parameter and the infrastructure creates Azure Managed Redis (Balanced_B0, the smallest size) and wires the connection string through Key Vault.

💡 Start with the cheapest option that is correct, and make the expensive option a parameter rather than a rewrite.

🧠 Secrets and observability

Secrets: Azure Key Vault in RBAC mode

The best secret is one that doesn't exist. Chapter 13 shows how managed identities remove passwords from SQL, Service Bus and the container registry entirely. Key Vault is for what's left: in Ledgerly, exactly one secret, the Redis access key, and only when Redis is enabled.

Sources: RBAC vs access policies, Key Vault RBAC guide.

Observability: Application Insights and Log Analytics

There is only one shape left for Application Insights: workspace-based. Classic Application Insights resources are retired, and all telemetry is stored in a Log Analytics workspace and billed through it (workspace-based resources). Chapters 15 and 16 cover the telemetry itself. The menu decision here is about cost: Log Analytics ingestion is often the surprise on the bill. Sampling, a daily cap and a sensible retention period are the levers (sampling).

💻 In Ledgerly: a hard daily cap

📄 sample/infra/modules/monitoring.bicep

resource workspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
  name: 'log-${name}'
  location: location
  tags: tags
  properties: {
    sku: { name: 'PerGB2018' }
    retentionInDays: 30
    workspaceCapping: { dailyQuotaGb: 1 } // 💰 a hard daily cap keeps a learning subscription safe
  }
}

resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
  // ...
  properties: {
    Application_Type: 'web'
    WorkspaceResourceId: workspace.id
  }
}

• PerGB2018 is pay per GB ingested, and retentionInDays: 30 keeps a month of data.
• dailyQuotaGb: 1 stops ingestion for the rest of the day once 1 GB has arrived. Priya objects ("a cap means blind spots during an incident"), so the team records it as a beta setting to revisit with real traffic data.

💡 Telemetry is a product with a price per GB: decide what you keep, for how long and at what sample rate.

🧠 What actually drives the bill

Now you can answer Elena. Not with a number, but with a table of drivers, where each one lives in Ledgerly's code, and the lever that controls it. Prices change and differ by region, so the source of truth is each service's pricing page and the Azure Pricing Calculator 🔧.

Sources: Container Apps billing, Azure SQL free offer.

Two details hide in that table:

• The worker never scales to zero. Its comment explains why: "the outbox relay and price alerts poll on a timer, so one replica must always run." That replica is your baseline Container Apps cost. A design that triggered the worker purely from the queue could scale to zero, at the price of a different outbox design.
• The API's health probes don't create telemetry. The service defaults filter /health and /alive out of traces, so probes don't eat the daily cap.

Budgets: an alarm, not a brake

Maya's last item: a budget on the resource group, with alerts on actual or forecasted cost. It's cheap insurance, but budgets don't stop resources: they notify, and stopping things needs automation wired to an action group. Cost data typically lands within 8 to 24 hours and budgets are evaluated every 24 hours, so a runaway loop can run for a day before anyone hears about it (create budgets).

Elena leaves with what she needed: "Most of the beta fits in free grants and serverless pauses. The fixed costs are the worker replica, the registry and Redis if we turn it on. The surprise risk is logs, and that's capped."

💡 You can't predict a cloud bill to the cent, but you can name every driver and put a lever next to it.

🗺️ Ledgerly on Azure, with its cost drivers

flowchart LR
    subgraph RG["Resource group rg-ledgerly-prod, one region"]
        subgraph ENV["Container Apps environment, Consumption profile"]
            Api["api<br/>min 0, max 10"]
            Worker["worker<br/>min 1, max 5"]
            Market["marketdata<br/>internal, min 0, max 3"]
            Job["job-migrations<br/>runs once per deploy"]
        end
        Sql[("Azure SQL serverless<br/>auto-pause, free offer")]
        Bus["Service Bus Standard<br/>pay per operation"]
        Redis[("Azure Managed Redis<br/>optional, off by default")]
        KV["Key Vault<br/>RBAC mode"]
        Logs["Log Analytics + App Insights<br/>1 GB daily cap, 30 days"]
        ACR["Container Registry<br/>Basic"]
    end
    Api -- "EF Core" --> Sql
    Worker -- "EF Core" --> Sql
    Worker -- "imports queue" --> Bus
    Api -. "L2 cache if enabled" .-> Redis
    KV -. "Redis secret reference" .-> Api
    ACR -- "images" --> ENV
    ENV -- "telemetry and logs" --> Logs

⚠️ Common traps

🧰 Helpers

A one-page "Azure menu" for any new service. Copy it into the ADR for each choice:

## Service choice: <compute | data | messaging | caching | secrets | observability>
- Requirement in one sentence:
- Options considered: (from the decision table)
- Chosen, and why:
- What makes it expensive, and the lever in Bicep:
- What would make us change our mind:
- 🔧 Volatile facts we relied on, with doc links:

Monthly cost review (15 minutes):

• [ ] Cost analysis grouped by the app tag: anything grow unexpectedly?
• [ ] Log Analytics ingestion: close to the daily cap?
• [ ] Azure SQL: when does the free allowance run out?
• [ ] Any resource without tags? (It was probably created by hand.)

Make it permanent:

• Put names, tags and SKUs in Bicep (chapter 11), so a reviewer sees every cost decision in a pull request.
• Add one ADR per menu decision, using the ADR template in the toolkit.
• Create a budget with forecast alerts on each environment's resource group as part of the one-time setup (chapter 12).
• Add "cost driver and lever" as a question in your PR template for infrastructure changes.

🧪 Try it yourself (optional, ~25 min)

No Azure subscription is needed for these steps.

1. Install the Bicep CLI. If you have the Azure CLI, run az bicep install. Otherwise install the standalone bicep CLI from the Bicep docs.
2. Find every cost lever in the parameters: bash cd sample grep -n "param " infra/main.bicep Mark the ones that change the bill: enableRedis, sqlUseFreeLimit and apiMinReplicas. Read their @description text.
3. Find the scale settings for each app: bash grep -n -A2 "scale:" infra/modules/apps.bicep Observe: the API uses apiMinReplicas, the worker is pinned to minReplicas: 1, and marketdata scales from 0 to 3.
4. Compile the Bicep to the ARM JSON that Azure would receive, and look for every SKU: bash bicep build infra/main.bicep --stdout | grep -n '"sku"' (With the Azure CLI: az bicep build --file infra/main.bicep --stdout.)
5. Open the Azure Pricing Calculator. Add Container Apps, Azure SQL Database (serverless), Service Bus Standard and Log Analytics. Model a quiet beta month and a busy one. Note which line moves the most between the two.
6. Write a short ADR: "Why Ledgerly runs on Azure Container Apps", with the cold-start trade-off and the condition that would make you switch apiMinReplicas to 1.

✅ Recap

1. Pick compute by the shape of the work: App Service for an IIS-like web app, Functions Flex Consumption for event handlers, Container Apps for services, workers and jobs, AKS only when you need the Kubernetes API.
2. Ledgerly uses Azure SQL serverless, Service Bus Standard (for duplicate detection), HybridCache with optional Azure Managed Redis, Key Vault in RBAC mode and workspace-based Application Insights.
3. Cost is a design property: scale to zero, free grants, auto-pause and a log ingestion cap are levers in Bicep, and budgets warn but never stop spending.

Next → Chapter 11: Infrastructure as code

Chapter 11: Infrastructure as code

⏱ About 35 min · You'll learn: Bicep basics (parameters, variables, modules, outputs, conditions, loops, existing, .bicepparam), how Ledgerly's main.bicep deploys in three phases, least-privilege role assignments for managed identities, how lint and what-if catch mistakes before Azure does, and how the database user for a managed identity gets created without anyone clicking.

📖 Story: "Show me the pull request"

Maya's Azure menu from chapter 10 is on the wiki. Priya has a free afternoon and offers to "just click it together in the portal, it's maybe twenty resources." Tomás Reyes, who owns the platform, doesn't even look up from his screen. "No."

He turns around. "If I click it, there is no record of what I clicked. Next month someone changes a setting during an incident, nobody remembers, and staging and production quietly drift apart. If it isn't in a pull request, it doesn't exist." He opens an empty file called main.bicep. "We write it down once. Azure reads it. Anyone can review it, rerun it or delete everything and get it back."

You think of the server build document at Nordbank Insurance: a 40-page Word file with screenshots, version 7, last updated by someone who left in 2019. In your Habits I brought with me notebook you write: "The runbook is the documentation." Next to it, Tomás writes in pencil: "The code is the runbook."

🏚️ Old way → 🚀 New way

🧠 Bicep in ten minutes

Bicep is a declarative language for Azure resources. You describe the end state; Azure Resource Manager (ARM) works out what to create or change. bicep build compiles it to an ARM JSON template, and that JSON is what Azure actually receives. For a C# developer, it reads like a typed configuration file with functions.

Two details trip up every newcomer:

• Dependencies are inferred. When sql uses identities.outputs.migratorClientId, Bicep knows the identity module must deploy first. You rarely write dependsOn.
• The API version is part of the type. Microsoft.App/containerApps@2025-01-01 and @2024-03-01 are different schemas. A property that exists in one may not exist in the other, which is exactly how lesson 7 below happened.

💻 In Ledgerly: parameters that explain themselves

📄 sample/infra/main.bicep

@description('Short name used in every resource name.')
@minLength(3)
@maxLength(12)
param appName string = 'ledgerly'

param location string = resourceGroup().location

@description('Container image tag (the git commit SHA). Empty = deploy the platform only.')
param imageTag string = ''

@description('Deploy the long-running apps. The pipeline sets this after the migration job succeeded.')
param deployApps bool = false
// ...
@description('0 = scale to zero (cheapest), 1 = always warm (no cold start).')
@minValue(0)
param apiMinReplicas int = 0

📄 sample/infra/main.bicepparam

// Values for the "production" environment. Secrets never go here: there are none to pass,
// because every service authenticates with a managed identity.
using 'main.bicep'

param appName = 'ledgerly'
param jwtAuthority = 'https://login.microsoftonline.com/<your-tenant-id>/v2.0'
param jwtAudience = 'api://ledgerly-api'
param corsOrigins = []
param enableRedis = false
param apiMinReplicas = 0

// imageTag and deployApps are passed by the pipeline on the command line.

using 'main.bicep' binds the file to the template, so a typo like param apiMinReplica = 0 is a compile error, not a silently ignored value. A second environment is a second file (staging.bicepparam), not a second template. Before your first real deployment, replace <your-tenant-id> with your tenant id (chapter 12).

💡 A good parameter file reads like the environment's spec sheet: everything that differs, nothing that doesn't, and no secrets.

🧠 One template, three phases

A naive template deploys everything at once. That fails on day one (the apps reference an image tag that doesn't exist yet in a registry the same deployment creates), and it's wrong after day one (the new API would start before the migrations ran).

Ledgerly's main.bicep solves both with two parameters and two conditions. The header comment is the design document.

💻 In Ledgerly: phases as conditions

📄 sample/infra/main.bicep

// Ledgerly on Azure. Resource-group scope; the deploy workflow runs it in three phases:
//   1. imageTag = ''                       -> platform only (registry, data, messaging, environment)
//   2. imageTag = <sha>, deployApps = false -> + the migration job with the new image (pipeline runs it)
//   3. imageTag = <sha>, deployApps = true  -> + api, worker, marketdata on the new image
// Deployments are incremental and idempotent: re-running a phase changes only what differs.
targetScope = 'resourceGroup'
// ...
module migrationJob 'modules/migration-job.bicep' = if (!empty(imageTag)) {
  name: 'migration-job'
  params: {
    // ...
    image: '${registry.outputs.loginServer}/ledgerly-migrations:${imageTag}'
    identityId: identities.outputs.migratorId
    // ...
  }
}

module apps 'modules/apps.bicep' = if (deployApps && !empty(imageTag)) {
  name: 'apps'
  params: {
    // ...
    cacheSecretUri: enableRedis ? redis!.outputs.secretUri : ''
    // ...
  }
}
// ...
output apiUrl string = (deployApps && !empty(imageTag)) ? apps!.outputs.apiUrl : ''

Three Bicep details make this work:

• Incremental mode. A resource-group deployment adds and updates resources, but leaves resources that aren't in the template alone. So phase 1 on the second day doesn't delete the apps that phase 3 created yesterday; it just confirms the platform is unchanged.
• The ! operator. redis and apps are conditional modules, so their outputs might not exist. redis!.outputs.secretUri tells the compiler "I've checked the condition myself"; it's only evaluated when enableRedis is true. It works like C#'s null-forgiving operator.
• Deterministic names. Every resource name comes from name (ledgerly- plus six characters derived from the resource group id), so each phase targets the same resources again.

Faster paths, and why the course doesn't take them

You don't have to write Bicep by hand. Know the alternatives:

A practical path: start with aspire publish to see what it generates, then own the Bicep once you need to change it.

💡 Ordering belongs in the template's design, not in a human's memory: conditions plus a pipeline turn "deploy in the right order" into code.

🗺️ The module graph

flowchart TB
    Main["main.bicep<br/>params and phases"]
    Mon["monitoring<br/>Log Analytics, App Insights"]
    Id["identity<br/>app and migrator"]
    Reg["registry<br/>AcrPull for both"]
    KV["keyvault<br/>Secrets User for app"]
    SB["servicebus<br/>Sender and Receiver for app"]
    Sql["sql<br/>migrator is Entra admin"]
    Redis["redis<br/>if enableRedis"]
    Env["environment<br/>Container Apps"]
    Job["migration-job<br/>if imageTag set"]
    Apps["apps<br/>if deployApps and imageTag"]
    Main --> Mon
    Main --> Id
    Id -- "principal ids" --> Reg
    Id -- "principal id" --> KV
    Id -- "principal id" --> SB
    Id -- "migrator name and client id" --> Sql
    KV -- "vault name" --> Redis
    Mon -- "workspace name" --> Env
    Env -- "environment id" --> Job
    Env -- "environment id" --> Apps
    Redis -. "secret URI" .-> Apps

🧠 Identities and least-privilege role assignments

On your old servers, the app pool ran as a domain account and someone added that account to a SQL login and an MSMQ ACL. In Azure, the equivalent is a managed identity: an identity in Microsoft Entra ID whose credentials Azure manages for you. A user-assigned managed identity is a resource you declare and then attach to apps; it survives redeploys and can be granted rights before any app exists. That's why Ledgerly uses user-assigned identities instead of system-assigned ones, which are created and deleted with each app.

💻 In Ledgerly: two identities, two jobs

📄 sample/infra/modules/identity.bicep

// Two user-assigned managed identities. No passwords or connection-string secrets anywhere:
//  - "app": what api, worker and marketdata run as (least privilege: read/write data, send/receive messages).
//  - "migrator": what the migration job runs as. It is the SQL Entra admin, so it can change the schema.
// ...
resource app 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'id-${name}-app'
  location: location
  tags: tags
}

The identity is a principal. Rights come from role assignments: a principal, a role definition and a scope. Ledgerly grants the smallest role at the narrowest scope:

💻 In Ledgerly: role assignments with guid() names

📄 sample/infra/modules/registry.bicep

var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d'
// ...
resource acrPull 'Microsoft.Authorization/roleAssignments@2022-04-01' = [for principalId in pullPrincipalIds: {
  name: guid(registry.id, principalId, acrPullRoleId)
  scope: registry
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId)
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}]

Read it line by line:

• Built-in role ids are fixed GUIDs. 7f951dda-... is AcrPull in every tenant. Using the id instead of the display name makes the template independent of language and renames.
• The name must be a GUID, and stable. guid(registry.id, principalId, acrPullRoleId) hashes its inputs into a deterministic GUID. Same scope, principal and role give the same name, so a rerun finds the existing assignment instead of failing with "role assignment already exists". Use newGuid() here and every deployment tries to create a duplicate.
• scope: registry puts the assignment on the registry, not the resource group. Least privilege applies to scope as much as to role.
• principalType: 'ServicePrincipal' tells Azure what kind of principal to expect. A freshly created managed identity can take a moment to replicate in Entra ID, and stating the type avoids a lookup that might fail during that window.

Service Bus needs two roles per principal, so it builds the list with map and flatten:

📄 sample/infra/modules/servicebus.bicep

resource roles 'Microsoft.Authorization/roleAssignments@2022-04-01' = [for item in flatten(map(dataPrincipalIds, p => [
  { principalId: p, roleId: senderRoleId }
  { principalId: p, roleId: receiverRoleId }
])): {
  name: guid(namespace.id, item.principalId, item.roleId)
  scope: namespace
  // ...
}]

If you know LINQ, this is dataPrincipalIds.SelectMany(p => new[] { (p, sender), (p, receiver) }).

The same file has one more assignment, and it's there because of a scaling detail. The worker's KEDA scale rule (chapter 18) reads the imports queue's message count through the Service Bus management API, and KEDA's docs say that needs Manage rights. Sender and Receiver don't include Manage, so without another role the worker would quietly never scale out. The fix grants Data Owner, but scoped to the one queue rather than the namespace:

📄 sample/infra/modules/servicebus.bicep

// 🔧 KEDA reads the queue's message count through the management API, which needs Manage rights.
// Sender and Receiver don't include them, so grant Data Owner on this one queue only, not the namespace.
resource scalerRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(imports.id, scalerPrincipalId, dataOwnerRoleId)
  scope: imports
  // ...
}

scope: imports works because a queue is a child resource with its own id, and Azure RBAC can scope a role to any resource. 🔧 Verify the scaler after your first deploy: if the worker stays at one replica while the queue grows, check the scale rule's events in the portal.

Jonas reviews the pull request: the API, worker and marketdata share the app identity, so the API could receive from the imports queue even though it never does. A per-app identity is stricter and costs a few more resources. They keep one identity for the beta and record it in an ADR. Least privilege is a dial; know where yours is set.

💡 A role assignment is code like any other: reviewed in a pull request, named deterministically, scoped as narrowly as the work allows.

🧠 Catch it before Azure does: lint, build and what-if

Bicep has a compiler and a linter, and you should treat their output exactly like C# compiler warnings: fix them, then make CI enforce it.

💻 In Ledgerly: infrastructure gets a CI job

📄 .github/workflows/ci.yml

  infra:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - name: Lint and build Bicep
        run: |
          az bicep install
          az bicep lint --file infra/main.bicep
          az bicep build --file infra/main.bicep --stdout > /dev/null
          az bicep build-params --file infra/main.bicepparam --stdout > /dev/null

No Azure login is needed: the linter and compiler run offline. build-params checks the parameter file against the template's types.

Lesson 7: two mistakes Bicep caught first

This really happened while building the sample.

BCP138. The first version of the API's environment variables put the CORS loop directly inside concat():

// illustrative, not in the sample: the first attempt, rejected by bicep build with BCP138
env: concat(commonEnv, [ /* ... */ ], [for (origin, i) in corsOrigins: { name: 'Cors__AllowedOrigins__${i}', value: origin }])

bicep build refused it: a for expression can't be nested inside a function call in that position. The fix was to move the loop into a variable and pass the variable:

📄 sample/infra/modules/apps.bicep

var corsEnv = [for (origin, i) in corsOrigins: { name: 'Cors__AllowedOrigins__${i}', value: origin }]
// ...
          ], empty(cacheSecretUri) ? [] : [
            { name: 'ConnectionStrings__cache', secretRef: 'cache-connection' }
          ], corsEnv)

BCP037. The container apps were first declared with API version 2024-03-01, and the linter warned that identity was not a known property on the worker's KEDA scale rule. On that schema, the managed-identity setting for a custom scaler didn't exist, so Azure would likely have ignored it and the scaler would have had no way to authenticate. Moving to Microsoft.App/containerApps@2025-01-01 fixed it:

📄 sample/infra/modules/apps.bicep

            name: 'imports-queue'
            custom: {
              type: 'azure-servicebus'
              metadata: {
                namespace: serviceBusNamespace
                queueName: 'imports'
                messageCount: '20'
              }
              identity: identityId
            }

The lesson: a warning about an unknown property is not noise. It usually means "this setting will be silently dropped." Since then, lint is a CI job.

What-if: the diff before the deploy

Lint proves the template is valid. What-if shows what it would change in a real resource group: creates, modifies and deletes, without applying anything (what-if).

# 🧪 needs an Azure login and an existing resource group
az deployment group what-if -g <rg> -f infra/main.bicep -p infra/main.bicepparam

🧪 Not run by the author: this step was written from the docs and validated with bicep build only. Expect small differences.

Related options from the docs: az deployment group create ... --confirm-with-what-if (-c) shows the preview and asks before applying, and --no-pretty-print returns JSON, which a PR workflow can post as a comment. Ledgerly doesn't run what-if in CI yet, because that would need Azure credentials on pull requests. It's a good next step once the OIDC setup from chapter 12 exists, with a read-only identity.

💡 Lint answers "is this valid?", what-if answers "what will this change?". You want both before anything touches production.

🗺️ From edit to Azure

flowchart LR
    Edit["Edit a .bicep file"] --> Local["bicep lint<br/>bicep build"]
    Local --> PR["Pull request"]
    PR --> CI["CI infra job<br/>lint, build, build-params"]
    CI -- "fails" --> Edit
    CI -- "passes" --> Review["Review<br/>roles, SKUs, cost"]
    Review --> WhatIf["what-if<br/>optional, needs Azure"]
    WhatIf --> Merge["Merge to main"]
    Merge --> Deploy["deploy.yml<br/>three phases"]

🧠 The database user nobody has to click

There's one permission Bicep can't grant: a database user inside Azure SQL. Role assignments live in Azure Resource Manager. Database users live inside the database, and only a principal that can sign in to SQL can create them.

Ledgerly's design:

1. The SQL server has Entra-only authentication, and its Entra admin is the migrator identity.
2. The migration job runs as the migrator, so it can change the schema.
3. After migrating, the same job creates a database user for the app identity and gives it read and write rights, nothing more.

📄 sample/infra/modules/sql.bicep

    administrators: {
      administratorType: 'ActiveDirectory'
      principalType: 'Application'
      login: adminIdentityName
      sid: adminIdentityClientId // 🔧 for a managed identity, the Learn Bicep sample uses the client id
      tenantId: subscription().tenantId
      azureADOnlyAuthentication: true
    }

Lesson 8: FROM EXTERNAL PROVIDER needs Graph, WITH SID doesn't

The documented way to create a user for an Entra principal is CREATE USER [name] FROM EXTERNAL PROVIDER. To resolve the name, the SQL server looks the principal up in Microsoft Entra ID, which requires the server itself to have permission to read the directory through Microsoft Graph. Granting that is a tenant-level step that many organizations reserve for administrators, and it would have been the one manual step in an otherwise automated setup.

The alternative: tell SQL the identity's id directly. CREATE USER [name] WITH SID = <id>, TYPE = E maps an external (Entra) principal without a directory lookup. For a managed identity, the SID is the client id as bytes.

📄 sample/src/Ledgerly.MigrationService/Program.cs

    /// <summary>
    /// CREATE USER ... WITH SID, TYPE = E maps a managed identity (by its client id) without needing Microsoft Graph
    /// permissions on the SQL server. Idempotent, so it is safe on every deployment.
    /// </summary>
    private static async Task EnsureAppUserAsync(LedgerlyDbContext db, string name, Guid clientId, CancellationToken ct)
    {
        var user = name.Replace("]", "]]", StringComparison.Ordinal);
        var sid = "0x" + Convert.ToHexString(clientId.ToByteArray());
        var sql = $"""
            IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = N'{user.Replace("'", "''", StringComparison.Ordinal)}')
                CREATE USER [{user}] WITH SID = {sid}, TYPE = E;
            ALTER ROLE db_datareader ADD MEMBER [{user}];
            ALTER ROLE db_datawriter ADD MEMBER [{user}];
            """;

#pragma warning disable EF1002 // values come from deployment configuration, are escaped above, and DDL cannot be parameterized
        await db.Database.ExecuteSqlRawAsync(sql, ct);
#pragma warning restore EF1002
    }

• Guid.ToByteArray() produces the byte order SQL expects for the SID, and Convert.ToHexString turns it into a 0x... literal.
• IF NOT EXISTS makes it idempotent, so it runs safely on every deployment.
• DDL can't take parameters, so the name is escaped for both [...] and N'...', and the analyzer warning (EF1002) is suppressed with a reason, not blindly.
• It only runs when Database:AppUser:Name and ClientId are configured. The migration job module sets them from the identity module's outputs, so locally (with Aspire and a SQL container) the step is simply skipped.

Elena asks why this matters for a PM. Tomás: "It means a new environment is git push plus one-time OIDC setup. No ticket to the identity team, no DBA."

💡 When the "last manual step" needs elevated rights, look for a design that removes the step rather than a person who can do it.

⚠️ Common traps

🧰 Helpers

A minimal module template (copy for each new resource type):

// illustrative, not in the sample: a starting point for a new module
param location string
param name string
param tags object

resource thing '<Provider/type>@<api-version>' = {
  name: '<prefix>-${name}'
  location: location
  tags: tags
  properties: {}
}

output id string = thing.id

Add role assignments by copying the acrPull loop from registry.bicep and changing the scope and role id.

PR review checklist for Bicep:

• [ ] Every new resource has tags: tags and a name derived from name.
• [ ] Every role assignment uses guid() and the narrowest scope.
• [ ] No secret in parameters or outputs, and a 💰 note for any SKU change.

Make it permanent:

• Keep the CI infra job required on pull requests (chapter 8's branch protection).
• Add bicep lint to your pre-commit habits: cd sample && bicep lint infra/main.bicep.
• Copy the toolkit's main.bicep pointer and module layout for new services (toolkit).
• Once OIDC exists (chapter 12), add a what-if job on PRs that touch sample/infra/**, with a read-only identity.

🧪 Try it yourself (optional, ~30 min)

Steps 1 to 4 run locally without Azure.

1. Install Bicep: az bicep install if you have the Azure CLI, otherwise the standalone bicep CLI.
2. Build and lint: bash cd sample bicep lint infra/main.bicep bicep build infra/main.bicep --stdout > main.json bicep build-params infra/main.bicepparam --stdout Open main.json and find the role assignment names: they are guid(...) expressions that ARM evaluates at deploy time. Delete main.json when you're done.
3. Reproduce lesson 7. In infra/modules/apps.bicep, temporarily replace corsEnv in the API's env with the loop itself: [for (origin, i) in corsOrigins: { name: 'Cors__AllowedOrigins__${i}', value: origin }]. Run bicep build infra/main.bicep and read the error. Then revert with git checkout -- infra/modules/apps.bicep.
4. Add a tag. In main.bicep, add environment: 'production' to var tags, build again and confirm every resource in main.json picks it up. Revert.
5. 🧪 With an Azure subscription and a resource group, run what-if: bash az deployment group what-if -g <rg> -f infra/main.bicep -p infra/main.bicepparam

   🧪 Not run by the author: this step was written from the docs and validated with bicep build only. Expect small differences.

On an empty group, everything shows as "create". Run phase 1 for real (chapter 12 does this in the pipeline), then run what-if again: it should show almost no changes. That's idempotency.

✅ Recap

1. Bicep turns infrastructure into reviewed code: parameters and .bicepparam files per environment, modules for structure, conditions and loops for variation, and lint plus build in CI.
2. Ledgerly's main.bicep deploys in three phases (platform, migration job, apps), and every identity gets the narrowest role at the narrowest scope, with guid() names so reruns are idempotent.
3. The migration job creates the app's database user with CREATE USER ... WITH SID, TYPE = E, so no portal clicks and no Graph permissions are needed.

Next → Chapter 12: CD to Azure with OIDC

Chapter 12: CD to Azure with OIDC

⏱ About 40 min · You'll learn: how GitHub Actions signs in to Azure with OIDC and no stored secret, how to set up the federated credential and the deployer's roles, how Ledgerly's deploy.yml builds once and deploys in three phases with a migration job and a smoke test, and how to roll back and change schemas without downtime.

📖 Story: The first real deploy

The Bicep from chapter 11 is merged, the CI infra job is green and Elena has a date for the beta. Tomás asks the question that decides the whole design: "How does GitHub get into our Azure subscription?"

You know the answer from Nordbank Insurance. A service account with a password that never expires, pasted into the build server's credential store in 2017. Everyone knew it was there. Nobody knew who else had copied it. When the auditor asked, the answer was a long silence. In your Habits I brought with me notebook you write: "The deploy account has a password. Rotation is a project."

Jonas shakes his head before you finish describing it. "No password. No client secret. GitHub proves who it is with a token that lives for a few minutes, and Azure decides whether to trust it. If someone steals that token tomorrow, it's already useless." Maya pulls up deploy.yml. "And the deploy is a workflow anyone can read. If it isn't in the file, it doesn't happen in production."

🏚️ Old way → 🚀 New way

🧠 OIDC: signing in without a secret

OpenID Connect (OIDC) lets GitHub Actions prove its identity to Azure with a token that GitHub signs and Azure verifies. Nothing secret is stored in GitHub. The setup has two halves:

1. In GitHub, the workflow asks for an ID token. That needs permissions: id-token: write.
2. In Azure, an identity has a federated credential that says: "trust tokens from this issuer, for this audience, with exactly this subject." The identity can be an Entra app registration or a user-assigned managed identity (GitHub OIDC in Azure, Azure Login with OIDC).

The subject is where the security lives (OIDC reference):

If the job declares an environment:, the subject is the environment form, not the branch form. Ledgerly's deploy job uses environment: production, so its federated credential uses repo:<owner>/<repo>:environment:production. That's a strong pin: only jobs that pass the production environment's protection rules can sign in.

🔧 The subject format is changing for new repositories. Repositories created after 2026-07-15 get an immutable subject that includes the owner and repository ids, for example repo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/main. Older repositories keep the classic format unless they opt in, and a rename or transfer after that date switches a repository to the new format. A fork is a new repository. The environment form follows the same pattern for the prefix; check the docs and the actual claim before you create the credential, because a single character of difference means "no".

💻 In Ledgerly: permissions and the login step

📄 .github/workflows/deploy.yml

permissions:
  id-token: write # request the OIDC token for azure/login
  contents: read
# ...
      - name: Sign in to Azure (OIDC, no secret)
        uses: azure/login@v3
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

azure/login@v3 🔧 requests the GitHub token, sends it to Entra ID and gets back an Azure access token for the identity. Every az command after it runs as that identity. There is no creds input with a JSON secret: that's the legacy way.

Why these are variables, not secrets

Ledgerly stores four repository variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID and AZURE_RESOURCE_GROUP. Many examples use secrets for the first three, and that works too. Ledgerly uses variables on purpose:

• They're identifiers, not credentials. A client id without a matching federated credential is useless, in the same way a username without a password is. The trust lives in Azure, pinned to your repository and environment.
• Variables can gate jobs. The workflow's if: checks vars.AZURE_CLIENT_ID != '', so the deploy switches itself off in forks and in your clone until you set it up. The secrets context can't be used that way in a job's if:.
• Variables are readable in logs, which makes "which subscription did this deploy to?" a question with an answer.

What the deployer identity may do

The deployer creates resources and role assignments (chapter 11's guid() assignments), and pushes images. That needs three things on the resource group:

Scope all three to the resource group, never the subscription. The identity can then do anything inside rg-ledgerly-prod and nothing outside it.

💡 OIDC moves trust from "who knows the password" to "which repository, which environment": there's nothing in GitHub worth stealing.

🗺️ The token exchange

sequenceDiagram
    participant Job as "Deploy job in production"
    participant GH as "GitHub OIDC provider"
    participant Entra as "Microsoft Entra ID"
    participant ARM as "Azure Resource Manager"
    Job->>GH: Request an ID token for the Azure token exchange audience
    GH-->>Job: Signed JWT with the environment production subject
    Job->>Entra: Exchange the JWT, client id from repository vars
    Entra->>Entra: Match issuer, audience and subject on the federated credential
    Entra-->>Job: Short-lived Azure access token
    Job->>ARM: az deployment group create as the deployer identity
    ARM-->>Job: Allowed by the roles on the resource group

🧠 One-time setup

This is the only manual part, and you do it once per environment. It's written as Azure CLI commands so you can keep it in your repo as a script. You could also let azd pipeline config create the credential and variables for you 🔧 (azd pipelines).

🧪 Not run by the author: this step was written from the docs and validated with bicep build only. Expect small differences.

# illustrative, not in the sample: one-time setup for the production environment
# Prerequisites: az login (as someone who can assign roles), gh auth login, and the repo cloned.
RG=rg-ledgerly-prod
LOCATION=westeurope            # pick your region (chapter 10)
REPO=<owner>/<repo>            # check the real sub claim format (classic or immutable)

az group create --name "$RG" --location "$LOCATION"

# A user-assigned managed identity for the pipeline (not the app identities from Bicep).
az identity create --name id-github-deployer --resource-group "$RG"
CLIENT_ID=$(az identity show --name id-github-deployer --resource-group "$RG" --query clientId -o tsv)
PRINCIPAL_ID=$(az identity show --name id-github-deployer --resource-group "$RG" --query principalId -o tsv)

# Trust GitHub tokens from the production environment of this repository only.
az identity federated-credential create \
  --name github-production \
  --identity-name id-github-deployer \
  --resource-group "$RG" \
  --issuer https://token.actions.githubusercontent.com \
  --subject "repo:$REPO:environment:production" \
  --audiences api://AzureADTokenExchange

# Roles on the resource group only.
RG_ID=$(az group show --name "$RG" --query id -o tsv)
for role in "Contributor" "Role Based Access Control Administrator" "AcrPush"; do
  az role assignment create \
    --assignee-object-id "$PRINCIPAL_ID" \
    --assignee-principal-type ServicePrincipal \
    --role "$role" \
    --scope "$RG_ID"
done

# Identifiers, not secrets: store them as repository variables.
gh variable set AZURE_CLIENT_ID --body "$CLIENT_ID"
gh variable set AZURE_TENANT_ID --body "$(az account show --query tenantId -o tsv)"
gh variable set AZURE_SUBSCRIPTION_ID --body "$(az account show --query id -o tsv)"
gh variable set AZURE_RESOURCE_GROUP --body "$RG"

Then, in GitHub:

1. Create the production environment (Settings → Environments). Add required reviewers (up to 6 people or teams, one approval is enough), turn on prevent self-review, and restrict deployment branches to main (environments). 🔧 On Free, Pro and Team plans, required reviewers and wait timers only work for public repositories.
2. Edit sample/infra/main.bicepparam: replace <your-tenant-id> in jwtAuthority and set jwtAudience to your API's app registration (chapter 13).
3. Push to main. Watch CI, then the deploy waits for approval.

One caution on the setup itself: the deployer identity lives in the resource group it deploys to. Don't delete that group to "start fresh" unless you're ready to repeat this section. Teams with several environments usually keep pipeline identities in a separate resource group.

💡 Keep the one-time setup as a script in the repo: "manual" should mean "run once", not "remember how".

🧠 The pipeline, step by step

Trigger, gate and concurrency

📄 .github/workflows/deploy.yml

on:
  workflow_run:
    workflows: [ci]
    types: [completed]
    branches: [main]
  workflow_dispatch:
# ...
# Never run two deployments at once, and never cancel one halfway.
concurrency:
  group: deploy-production
  cancel-in-progress: false

env:
  # ...
  RESOURCE_GROUP: ${{ vars.AZURE_RESOURCE_GROUP }}
  # The exact commit CI tested. Every image is tagged with it, so a revision maps back to a commit.
  SHA: ${{ github.event.workflow_run.head_sha || github.sha }}

jobs:
  deploy:
    # workflow_run also fires for pull requests (even from forks whose branch is named main), so only
    # deploy CI runs that came from a push to this repository, never someone else's code.
    if: >
      vars.AZURE_CLIENT_ID != '' &&
      (github.event_name == 'workflow_dispatch' ||
        (github.event.workflow_run.conclusion == 'success' &&
         github.event.workflow_run.event == 'push' &&
         github.event.workflow_run.head_repository.full_name == github.repository))
    runs-on: ubuntu-latest
    timeout-minutes: 45
    environment:
      name: production # protection rules (reviewers, branch filter) live on the environment
      url: ${{ steps.apps.outputs.apiUrl }}

• workflow_run starts this workflow when the ci workflow completes for main. "Completed" includes failures, so the job's if: also requires conclusion == 'success'. workflow_dispatch adds a manual "Run workflow" button.
• The two extra checks in if: close a hole Jonas found in review. branches: [main] matches the head branch name, and CI also runs on pull requests, so a pull request from a fork whose branch happens to be called main would complete CI and trigger this workflow. Requiring event == 'push' and the same repository means only code that was actually pushed to this repository's main can reach Azure.
• SHA is the commit CI actually tested (head_sha), not whatever main points to by the time this runs. The checkout step uses ref: ${{ env.SHA }}.
• concurrency with cancel-in-progress: false: the docs' example cancels superseded runs (concurrency). For a deploy that runs migrations, cancelling halfway is worse than waiting, so a second deploy queues instead.
• environment: production pauses the job until a reviewer approves, makes the OIDC subject the environment form and shows the API URL on the deployment.

Three phases, built once

📄 .github/workflows/deploy.yml

      - name: Build and push images (no Dockerfile)
        env:
          LOGIN_SERVER: ${{ steps.platform.outputs.loginServer }}
        run: |
          az acr login --name "${{ steps.platform.outputs.registry }}"
          for project in Ledgerly.Api Ledgerly.Worker Ledgerly.MarketData Ledgerly.MigrationService; do
            dotnet publish "src/$project" -c Release /t:PublishContainer \
              -p:ContainerRegistry="$LOGIN_SERVER" -p:ContainerImageTag="$SHA"
          done

Build once, promote the tag. CI builds the images too, but tags them ci-<sha> and never pushes them: it proves they build. The deploy builds once per commit and pushes once. After that, the migration job and all three apps use the same tag, and nothing is rebuilt. When you add a staging environment, keep that rule: build and push in the first environment, then deploy the existing tag to the next one. A revision's image tag always maps back to one commit.

The migration gate

📄 .github/workflows/deploy.yml

      - name: Run migrations and wait
        env:
          JOB: ${{ steps.platform.outputs.job }}
        run: |
          execution=$(az containerapp job start -n "$JOB" -g "$RESOURCE_GROUP" --query name -o tsv)
          echo "Started $execution"
          for i in $(seq 1 60); do
            status=$(az containerapp job execution show -n "$JOB" -g "$RESOURCE_GROUP" \
              --job-execution-name "$execution" --query properties.status -o tsv)
            echo "[$i] $status"
            case "$status" in
              Succeeded) exit 0 ;;
              Failed|Stopped|Degraded) echo "::error::Migration $execution ended as $status. See its logs in Log Analytics."; exit 1 ;;
            esac
            sleep 10
          done
          echo "::error::Migration did not finish within 10 minutes"; exit 1

az containerapp job start returns immediately with an execution name, so the step polls: up to 60 times, every 10 seconds. The job itself (chapter 11) has replicaTimeout: 600 and one retry. The migration service sets Environment.ExitCode = 1 on any failure, so a failed migration becomes a failed execution, the step exits 1 and phase 3 never runs. The old apps keep serving on the old, untouched schema.

The smoke test

📄 .github/workflows/deploy.yml

      # The deployment "succeeding" only means Azure accepted it. This proves the new revision answers.
      - name: Smoke test
        run: |
          for i in $(seq 1 30); do
            if curl -fsS "${{ steps.apps.outputs.apiUrl }}/alive"; then echo; echo "API is up"; exit 0; fi
            sleep 10
          done
          echo "::error::API did not become healthy"; exit 1

With apiMinReplicas = 0, the first call may hit a cold start, so the loop allows up to five minutes. /alive is mapped in every environment by the service defaults (unlike the Aspire template's development-only default), because the Container Apps probes need it too.

💡 A pipeline is a sequence of gates: tests, approval, migrations, smoke test. Each one is a place where a bad change stops before users see it.

🗺️ From merge to running revision

flowchart TB
    Merge["Merge to main"] --> CI["ci workflow<br/>build, test, containers, infra lint"]
    CI -- "success" --> Gate{"AZURE_CLIENT_ID set<br/>and CI succeeded?"}
    Gate -- "no" --> Skip["Job skipped"]
    Gate -- "yes" --> Approve["Environment production<br/>reviewer approves"]
    Approve --> Login["azure/login<br/>OIDC"]
    Login --> P1["Phase 1<br/>platform"]
    P1 --> Build["Build and push<br/>tag = commit SHA"]
    Build --> P2["Phase 2<br/>migration job image"]
    P2 --> Run{"Migration job<br/>succeeded?"}
    Run -- "no" --> Stop["Fail, old apps keep running"]
    Run -- "yes" --> P3["Phase 3<br/>new app revisions"]
    P3 --> Smoke["Smoke test /alive"]

🧠 Revisions, rollback and zero-downtime schema changes

Revisions in single mode

Every change to an app's template (a new image, an environment variable, a scale rule) creates a new revision, an immutable snapshot (revisions). Ledgerly's apps use activeRevisionsMode: 'Single', the default: the new revision replaces the old one with zero downtime, once its startup and readiness probes pass. If the new revision never becomes ready, it doesn't get traffic, and the smoke test fails the pipeline.

Multiple mode keeps several revisions active and lets you split traffic by percentage, for canary or blue/green releases, with labels that give a revision a stable URL for testing (traffic splitting). Ledgerly starts with single mode because it's simpler; Priya has multiple mode on her list for after the beta.

Rollback

Break glass, when even a pipeline run is too slow:

# illustrative, not in the sample: point the API back at the previous image (🧪 check the az containerapp docs)
az containerapp update -n api -g rg-ledgerly-prod --image <loginServer>/ledgerly-api:<previous-sha>

That creates a new revision outside the pipeline. The next deploy will overwrite it, so follow up with a revert on main.

The rollback rows have one hidden requirement: the previous code must still work against the current schema. That's what expand and contract guarantees.

Expand and contract

Suppose you rename Portfolio.Name to Portfolio.DisplayName. A single migration that renames the column breaks the old revision for the seconds (or minutes) between phase 2 and phase 3, and it makes rollback impossible. Split it across releases:

Each release is safe to roll back by one step. It's slower than one big migration, and that's the price of no maintenance window.

💡 Rollback is only real if the previous version can run against today's schema: design migrations so it always can.

🗺️ Expand and contract as states

stateDiagram-v2
    [*] --> OldOnly: schema has Name
    OldOnly --> Expanded: release 1 adds DisplayName
    Expanded --> Switched: release 2 code uses DisplayName only
    Switched --> Contracted: release 3 drops Name
    Contracted --> [*]
    Expanded --> OldOnly: rollback is safe, Name still exists
    Switched --> Expanded: rollback is safe, both columns exist

⚠️ Common traps

🧰 Helpers

Hardened gate for any workflow_run deploy (the same condition the sample uses, ready to paste into your own workflows):

    if: >
      vars.AZURE_CLIENT_ID != '' &&
      (github.event_name == 'workflow_dispatch' ||
       (github.event.workflow_run.conclusion == 'success' &&
        github.event.workflow_run.event == 'push' &&
        github.event.workflow_run.head_repository.full_name == github.repository))

Pre-flight checklist for the first deploy:

• [ ] The real sub claim matches the federated credential (environment form, classic or immutable).
• [ ] Repository variables set: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP.
• [ ] The production environment has reviewers and a main-only branch rule.
• [ ] jwtAuthority and jwtAudience in main.bicepparam are real values.
• [ ] A budget exists on the resource group (chapter 10).

Make it permanent:

• Commit the one-time setup script (as docs/setup-production.sh or similar) so the next environment is a copy and a rename.
• Copy deploy.yml from the toolkit and adjust paths, projects and resource names.
• Add "Is this migration expand-only?" to your PR template for any change under Data/Migrations.
• Practice a rollback once, on a quiet day, before you need it.

🧪 Try it yourself (optional, ~45 min)

1. Locally, no Azure: read .github/workflows/deploy.yml and trace one commit SHA through it: where is it set, which steps use it, and which image tags and deployment names it ends up in? Then check that bicep build-params infra/main.bicepparam still passes from cd sample.
2. Locally: run the migration service against your Aspire SQL with aspire run and find its "Database migrated" log line in the dashboard. That line is what the job execution logs show in Azure.
3. 🧪 With Azure: run the one-time setup script for your fork, create the production environment and push a commit to main. Approve the deployment and watch the three phases.

   🧪 Not run by the author: this step was written from the docs and validated with bicep build only. Expect small differences.

4. 🧪 With Azure: make a visible change (for example, a new field in an endpoint response), deploy it, then roll back by re-running the previous deploy run. Confirm with az containerapp revision list -n api -g <rg> -o table that a new revision appeared.

✅ Recap

1. OIDC replaces deploy secrets: GitHub issues a short-lived token, and Azure trusts it through a federated credential pinned to issuer, audience and an exact subject (the environment form for Ledgerly, and the immutable format for new repos 🔧).
2. The deployer needs Contributor, a role-assignment role and AcrPush on the resource group only, and its identifiers live in repository variables because they aren't secrets.
3. deploy.yml builds once per SHA and deploys in three gated phases (platform, migration job, apps), then smoke-tests, while revisions plus expand-and-contract migrations make rollback safe.

Next → Chapter 13: Identity and secrets

Chapter 13: Identity and secrets

⏱ About 40 min · You'll learn: how Ledgerly reaches SQL, Service Bus, Key Vault and the registry with managed identities instead of passwords, when to use DefaultAzureCredential and when to use ManagedIdentityCredential, how the API authenticates users with JWT bearer tokens and keeps each user's data private, and which few secrets remain and where they live.

📖 Story: The connection string in Slack

It's Tuesday morning. Jonas, the security engineer, sends you a screenshot without a greeting. It's a message from the team's Slack channel, eight weeks old, from the time before you joined. Someone was debugging a prototype and pasted a full connection string: Endpoint=sb://...;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=....

"Is that ours?" he asks.

You check. It belongs to a prototype namespace that nobody deleted. The key still works. Jonas rotates it, deletes the namespace, and then asks the question that matters: "Could the same thing happen with Ledgerly?"

You open servicebus.bicep together. One line answers him: disableLocalAuth: true. Ledgerly's namespace doesn't accept keys at all. Even if someone pasted the root key in a channel, it would be rejected. The worker connects with a managed identity that has two data roles, and there's nothing to paste.

"Good," Jonas says. "Now show me everything else."

That becomes the afternoon. Maya joins, and the three of you walk through every arrow in the architecture. For each one, Jonas asks the same two questions: "Who is calling?" and "What would an attacker need to steal to pretend to be them?"

In your notebook, under Habits I brought with me, you write: "Encrypt the connection strings section of web.config." Then you cross out the word "encrypt" and write "delete".

🏚️ Old way → 🚀 New way

🧠 Managed identity everywhere

A managed identity is a Microsoft Entra ID identity for a workload. Azure creates and stores its credentials, and the code asks the platform for a token when it needs one. You never see a password, so you can't paste it anywhere.

Container Apps supports two kinds (facts from the Container Apps managed identity docs):

• System-assigned: one per app, deleted with the app.
• User-assigned: a standalone resource that several apps can share.

Ledgerly uses two user-assigned identities, created before the apps exist so that role assignments and the SQL admin can refer to them (chapter 11 explains why the order matters).

💻 In Ledgerly: two identities, two jobs

📄 sample/infra/modules/identity.bicep

// Two user-assigned managed identities. No passwords or connection-string secrets anywhere:
//  - "app": what api, worker and marketdata run as (least privilege: read/write data, send/receive messages).
//  - "migrator": what the migration job runs as. It is the SQL Entra admin, so it can change the schema.
// ...
resource app 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'id-${name}-app'
  location: location
  tags: tags
}

resource migrator 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'id-${name}-migrator'
  location: location
  tags: tags
}

Splitting the identities is the important design choice. The apps can read and write rows, but they can't drop a table. Only the short-lived migration job can change the schema.

Now follow each arrow Jonas asked about:

💻 In Ledgerly: SQL without a password

📄 sample/infra/modules/apps.bicep

var sqlConnection = 'Server=tcp:${sqlServerFqdn},1433;Database=${databaseName};Authentication=Active Directory Managed Identity;User Id=${identityClientId};Encrypt=True;Connect Timeout=60'

var commonEnv = [
  { name: 'AZURE_CLIENT_ID', value: identityClientId } // makes Azure SDK credentials pick the user-assigned identity
  { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: appInsightsConnectionString }
]

Read the connection string closely. There's a server, a database, an authentication mode and a User Id that is the identity's client id, not a user name. Microsoft.Data.SqlClient asks the platform for a token for that identity and sends it to SQL. The SqlClient Entra authentication docs describe the options:

• Authentication=Active Directory Default walks the whole DefaultAzureCredential chain. It's convenient on a laptop, but the docs say it can be slow and isn't recommended for production.
• Authentication=Active Directory Managed Identity with User Id=<client id> is the production form for a user-assigned identity. That's what Ledgerly uses.

On the server side, sql.bicep sets azureADOnlyAuthentication: true, which disables SQL authentication entirely (Entra-only authentication). The database user for the app identity is created by the migration service with CREATE USER ... WITH SID = ..., TYPE = E, so the SQL server doesn't need Microsoft Graph permissions to look the identity up. Chapter 11 tells the story of how the team found that out.

💻 In Ledgerly: Service Bus without a key

📄 sample/infra/modules/servicebus.bicep

// Service Bus Standard (needed for duplicate detection). Local (SAS key) auth is disabled:
// only Entra identities with a data role can send or receive.
// ...
  properties: {
    disableLocalAuth: true
    minimumTlsVersion: '1.2'
  }

📄 sample/infra/modules/apps.bicep

            { name: 'ConnectionStrings__messaging', value: serviceBusFqns } // a namespace, not a key: Entra auth
// ...
            custom: {
              type: 'azure-servicebus'
              metadata: {
                namespace: serviceBusNamespace
                queueName: 'imports'
                messageCount: '20'
              }
              identity: identityId
            }

The worker's code doesn't change between your laptop and Azure: it calls builder.AddAzureServiceBusClient("messaging"). Locally, Aspire hands it an emulator connection string. In Azure, it gets only the namespace name, and the client authenticates with a token credential. The KEDA scale rule uses the same identity, so the scaler doesn't need a key either.

The registry follows the same pattern: adminUserEnabled: false in registry.bicep, and var registries = [ { server: registryServer, identity: identityId } ] in apps.bicep. Container Apps pulls images with the identity and the AcrPull role, so no registry password exists.

💡 For every arrow in your architecture, ask "what would an attacker need to steal?" With managed identities the answer becomes "control of the running workload", which is a much higher bar than "one line from a Slack message".

🗺️ Who can reach what

flowchart LR
    API["api"] -- "runs as" --> APPID["app identity<br/>user-assigned"]
    WORKER["worker"] -- "runs as" --> APPID
    MD["marketdata"] -- "runs as" --> APPID
    JOB["migrations job"] -- "runs as" --> MIGID["migrator identity<br/>user-assigned"]
    APPID -- "AcrPull" --> ACR["Container Registry<br/>admin user off"]
    MIGID -- "AcrPull" --> ACR
    APPID -- "Data Sender and Receiver" --> SB["Service Bus<br/>local auth off"]
    APPID -- "Key Vault Secrets User" --> KV["Key Vault<br/>RBAC mode"]
    APPID -- "db_datareader and db_datawriter" --> SQL["Azure SQL<br/>Entra-only auth"]
    MIGID -- "Entra admin, changes schema" --> SQL

Every arrow on the right is a role assignment or a database role in the Bicep or the migration service. If it isn't in the code, the access doesn't exist.

🧠 DefaultAzureCredential or ManagedIdentityCredential?

When Azure SDK clients need a token, they take a TokenCredential. The one you see in every quick start is DefaultAzureCredential. It tries a chain of credentials in order and uses the first that works. In Azure.Identity 1.21.0 🔧 the order is (credential chains):

1. Environment
2. Workload Identity
3. Managed Identity
4. Visual Studio
5. Visual Studio Code
6. Azure CLI
7. Azure PowerShell
8. Azure Developer CLI
9. Interactive browser (excluded by default)
10. Broker

That chain is why the same code works on your laptop (Visual Studio or Azure CLI sign-in) and in Azure (managed identity). It's also why it can surprise you. The SDK best practices are direct about it:

• Use deterministic credentials in production. Replace DefaultAzureCredential with a specific credential such as ManagedIdentityCredential, and pass the client id for a user-assigned identity.
• Or compose a ChainedTokenCredential, for example ManagedIdentityCredential and then AzureCliCredential, for a production-safe chain with a developer fallback.
• The reasons: probing adds latency and unpredictable behavior, and environment-dependent fallbacks are hard to debug.
• Reuse credential instances. Tokens are cached per instance, so creating a new credential per request throws the cache away.
• 🔧 The environment variable AZURE_TOKEN_CREDENTIALS narrows the default chain: prod keeps Environment, Workload Identity and Managed Identity, dev keeps the developer tools, or you can name one credential.

💻 In Ledgerly: no credential code at all

Ledgerly has no new DefaultAzureCredential() anywhere in its application code. Two things make that possible:

• SQL picks its credential from the connection string keyword. Active Directory Managed Identity with a User Id is already deterministic.
• Service Bus goes through the Aspire client integration, which builds a credential for you when the connection string is just a namespace. Check the Aspire Service Bus integration docs for the current default and for the settings that let you supply your own credential.

The AZURE_CLIENT_ID environment variable in commonEnv ties it together. A container app can have several user-assigned identities, and the variable tells Azure SDK credentials which one to use. Forget it, and authentication fails in Azure even though everything worked locally.

If you write your own SDK client registration, follow the best-practice pattern:

// illustrative, not in the sample
TokenCredential credential = builder.Environment.IsDevelopment()
    ? new DefaultAzureCredential()
    : new ManagedIdentityCredential(ManagedIdentityId.FromUserAssignedClientId(builder.Configuration["AZURE_CLIENT_ID"]));

builder.Services.AddSingleton(credential); // one instance, so its token cache is shared

🔧 The ManagedIdentityId factory is in recent Azure.Identity versions; check the API reference for the version you use.

💡 DefaultAzureCredential is a great developer experience and a poor production contract. In Azure, say exactly which identity you mean.

🧠 Users: JWT bearer and per-user data

Managed identities answer "which workload is calling Azure?". Users are a different question: "which person is calling the API, and which portfolios are theirs?"

The API uses JWT bearer authentication. A client gets an access token from an identity provider and sends it in the Authorization header. The API checks the signature, issuer, audience and lifetime, and then trusts the claims inside. No session, no cookie, no server-side state.

💻 In Ledgerly: two lines and a config section

📄 sample/src/Ledgerly.Api/Program.cs

// ── Security: JWT bearer. Settings come from "Authentication:Schemes:Bearer" ───────────────────
// Locally: `dotnet user-jwts create`. In Azure: Authority = your Entra ID tenant, audience = the API app.
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

AddJwtBearer() with no arguments reads its settings from the Authentication:Schemes:Bearer configuration section (configure JWT bearer authentication). That's what lets the same code accept two kinds of tokens:

• Locally, dotnet user-jwts create --project src/Ledgerly.Api issues a development token. The tool keeps its signing key in your user secrets and writes the issuer and audience it needs into the development configuration. --name sets the user name, which is handy for testing two users.
• In Azure, Bicep sets the authority and audience as environment variables:

📄 sample/infra/modules/apps.bicep

            { name: 'Authentication__Schemes__Bearer__Authority', value: jwtAuthority }
            { name: 'Authentication__Schemes__Bearer__ValidAudiences__0', value: jwtAudience }

The authority is your Entra ID tenant, and the audience is the API's app registration. The handler downloads the tenant's signing keys from the authority's metadata, so you never configure a key.

Microsoft.Identity.Web (4.16.1 🔧) is the other option. AddMicrosoftIdentityWebApi reads an AzureAd section and adds Entra-specific validation and helpers (protected web API configuration). Delegated scopes arrive in the scp claim and app roles in the roles claim (scopes and app roles). Ledgerly keeps plain AddJwtBearer so local and Entra tokens share one code path. When Leo builds the React SPA, it signs users in with MSAL.js and the authorization code flow with PKCE; the implicit flow isn't supported.

💻 In Ledgerly: a stable user id

📄 sample/src/Ledgerly.Api/ApiConventions.cs

    /// <summary>
    /// Stable user id. Entra ID puts the object id in "oid"; dev tokens from `dotnet user-jwts` use "sub"
    /// (mapped to NameIdentifier by the JWT handler).
    /// </summary>
    public static string GetOwnerId(this ClaimsPrincipal user) =>
        user.FindFirstValue("oid")
        ?? user.FindFirstValue("http://schemas.microsoft.com/identity/claims/objectidentifier")
        ?? user.FindFirstValue(ClaimTypes.NameIdentifier)
        ?? user.FindFirstValue("sub")
        ?? throw new InvalidOperationException("Authenticated user has no id claim.");

Each portfolio stores this id as OwnerId. Not the email, not the display name: those change, and an id that changes orphans data. The fallbacks exist because the JWT handler can map claim names, so oid may arrive under its long URI form and sub as NameIdentifier.

💻 In Ledgerly: authorization is a WHERE clause

📄 sample/src/Ledgerly.Api/Endpoints/PortfolioEndpoints.cs

        var group = app.MapGroup("/api/portfolios")
            .WithTags("Portfolios")
            .RequireAuthorization();
// ...
        var ownerId = user.GetOwnerId();
        var portfolio = await db.Portfolios.AsNoTracking()
            .Include(p => p.Transactions)
            .SingleOrDefaultAsync(p => p.Id == id && p.OwnerId == ownerId, ct);

        if (portfolio is null)
        {
            return TypedResults.NotFound();
        }

RequireAuthorization() on the group means "you must be signed in", and an anonymous call gets 401. The second check is per row: the query filters on both the id and the owner. If you ask for someone else's portfolio, the database returns nothing, and you get 404, not 403. A 403 would confirm that the id exists. Jonas calls this "don't answer questions nobody should be asking".

💡 Authentication is configuration. Authorization is code, and in a multi-user API most of it is a WHERE OwnerId = @me that you never forget.

🗺️ One request, two kinds of identity

sequenceDiagram
    participant SPA as "React SPA"
    participant Entra as "Microsoft Entra ID"
    participant Api as "Ledgerly.Api"
    participant Sql as "Azure SQL"
    SPA->>Entra: Sign in with authorization code and PKCE
    Entra-->>SPA: Access token for the API audience
    SPA->>Api: GET /api/portfolios/id with the bearer token
    Api->>Api: Validate signature, issuer, audience and lifetime
    Api->>Api: GetOwnerId reads the oid claim
    Api->>Entra: Token request as the app managed identity
    Entra-->>Api: Token for Azure SQL
    Api->>Sql: Select where Id and OwnerId match
    Sql-->>Api: No row, the portfolio belongs to someone else
    Api-->>SPA: 404 Not Found

Two identities take part in every request: the user, proven by the bearer token, and the workload, proven by the managed identity. The user never talks to SQL, and the API never sees the user's password.

🧠 The secrets that remain: Key Vault, CORS and Data Protection

After the identity work, Jonas asks for the list of real secrets in Ledgerly. It's short:

• The Redis access key, only when enableRedis is on. Redis is optional in Ledgerly (chapter 10).
• Nothing else that grants access. The Application Insights connection string is passed as a plain environment variable in the sample; it tells the SDK where to send telemetry.

💻 In Ledgerly: a Key Vault reference

The Redis connection string is built inside Bicep, written straight into Key Vault and never returned as an output. The API gets it through a Key Vault reference:

📄 sample/infra/modules/apps.bicep

      // A Key Vault reference: Container Apps fetches the value with the managed identity.
      secrets: empty(cacheSecretUri) ? [] : [
        { name: 'cache-connection', keyVaultUrl: cacheSecretUri, identity: identityId }
      ]
// ...
            { name: 'ConnectionStrings__cache', secretRef: 'cache-connection' }

Container Apps reads the secret with the app identity, which needs Key Vault Secrets User (Container Apps secrets). The value never passes through the GitHub workflow or the deployment outputs.

📄 sample/infra/modules/keyvault.bicep

// Key Vault in RBAC mode (access policies are legacy). Apps read secrets via Key Vault references
// in Container Apps, so the secret value never appears in the pipeline or in app settings.
// ...
    enableRbacAuthorization: true
    enableSoftDelete: true
    softDeleteRetentionInDays: 7

Key Vault facts worth knowing (Key Vault RBAC guide):

• Azure RBAC is the recommended permission model; vault access policies are legacy. 🔧 Starting with ARM API version 2026-02-01, new vaults default to RBAC.
• The data-plane roles are Key Vault Secrets User (read), Key Vault Secrets Officer (manage) and Key Vault Administrator. Apps get Secrets User, at vault scope or narrower.
• If an app reads Key Vault directly, use Azure.Extensions.AspNetCore.Configuration.Secrets (1.5.2 🔧) with AddAzureKeyVault; ConnectionStrings--Db becomes ConnectionStrings:Db (Key Vault configuration provider). Ledgerly doesn't need it.

The header of redis.bicep admits the gap: "Entra auth is the stronger option, see chapter 13." Azure Managed Redis supports Microsoft Entra ID authentication (Azure Managed Redis overview), and Aspire's Aspire.Microsoft.Azure.StackExchangeRedis package is the client side of it. With that in place you could turn off accessKeysAuthentication and delete the last secret. Redis is optional, so the team keeps the key for now, and Jonas puts the switch on the backlog with a date.

CORS for the SPA

Chapter 4 added the CORS policy. Here's how it reaches production: the allowed origins come from corsOrigins in main.bicepparam, and Bicep turns them into indexed environment variables.

📄 sample/infra/modules/apps.bicep

var corsEnv = [for (origin, i) in corsOrigins: { name: 'Cors__AllowedOrigins__${i}', value: origin }]

📄 sample/src/Ledgerly.Api/Program.cs

app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseCors(ApiPolicies.Spa);
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

UseCors runs before authentication, because a browser's preflight OPTIONS request carries no token and must still get CORS headers. Remember what CORS is: a browser rule about which sites may call your API from JavaScript. It isn't authentication. A script or curl ignores it, which is why the bearer token and the owner check do the real work.

Data Protection

ASP.NET Core Data Protection encrypts cookies and antiforgery tokens. Ledgerly's API uses bearer tokens with no cookies, so nothing depends on the key ring today. If you add cookie authentication or a backend-for-frontend later, all replicas must share one key ring, or a cookie written by one replica can't be read by another. Check the ASP.NET Core Data Protection docs for key storage options before you add cookies.

💡 Count your secrets. The goal isn't a better vault; it's a shorter list. Every secret you can replace with an identity is one less thing to rotate, scan for and explain.

🧠 The supply chain is part of security

Jonas's last stop isn't Azure at all. "Half of your code is other people's packages," he says. "Who checks them?"

💻 In Ledgerly: one package source

📄 sample/nuget.config

  <!-- Only nuget.org, no machine-wide feeds leaking in. Package source mapping blocks dependency-confusion attacks. -->
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>

<clear /> ignores feeds configured on the machine, and source mapping says which feed each package may come from. When you add a private feed, map your company's prefix to it, so a public package with the same name can't sneak in. NuGet audit proved its worth in chapter 3: it failed the build on a vulnerable transitive System.Security.Cryptography.Pkcs, fixed with transitive pinning.

💻 In Ledgerly: Dependabot and CodeQL

📄 .github/dependabot.yml

  - package-ecosystem: nuget
    directory: /sample
    schedule:
      interval: weekly
    groups:
      # One PR per family instead of twenty. Versions inside a family must move together.
      aspire:
        patterns: ["Aspire.*"]
# ...
  - package-ecosystem: github-actions
    directory: /

Dependabot opens pull requests for outdated NuGet packages and GitHub Actions, grouped by family so Aspire packages move together (Dependabot options). 🔧 Version updates have a default cooldown of 3 days, so brand-new releases aren't proposed until they've been out for a few days. CI tests every Dependabot PR like any other.

📄 .github/workflows/codeql.yml

  schedule:
    - cron: "17 3 * * 1" # weekly, catches new queries against unchanged code
# ...
      - uses: github/codeql-action/init@v4
        with:
          languages: csharp
          build-mode: none # no build needed for C#, analysis reads the source
      - uses: github/codeql-action/analyze@v4

CodeQL is static analysis. build-mode: none analyzes C# without a build, which keeps the workflow fast (configure code scanning). The weekly run matters: new queries find problems in code that hasn't changed. 🔧 Code scanning is free for public repositories; private and internal ones need GitHub Code Security.

Secret scanning and push protection

Secret scanning looks for known secret formats in the repository, and push protection blocks a push that contains one. Both are free and automatic for public repositories, and push protection for users is on by default there. 🔧 Repository-level push protection and private repositories need GitHub Secret Protection.

Jonas points out the limit: push protection guards Git, not Slack. The only complete fix for the story at the top of this chapter is the one you already made: have nothing worth pasting.

💡 You own every package and action in your build. Pin the sources, let a bot propose updates, let CI test them, and let a scanner read the code every week.

⚠️ Common traps

🧰 Helpers

The "no secrets" review for a new arrow (copy into your design notes):

• [ ] Who calls whom? Name the identity (app or migrator) and the target resource.
• [ ] Can the target use Microsoft Entra ID auth? If yes, disable keys or local users.
• [ ] Which data-plane role is the narrowest that works? Assign it in Bicep with a guid() name.
• [ ] If a secret is unavoidable, does it go from Bicep straight into Key Vault, with no output?
• [ ] Is AZURE_CLIENT_ID set on the app that uses the identity?

See what an identity can do 🧪 (illustrative, not in the sample):

# illustrative, not in the sample
# principal id of the app identity, from the Bicep output appPrincipalId or the portal
az role assignment list --assignee <app-principal-id> --all -o table
az servicebus namespace show -g <rg> -n <namespace> --query disableLocalAuth

🧪 Not run by the author: this step was written from the docs and validated with bicep build only. Expect small differences.

Make it permanent:

• Add "No new secrets, or a Key Vault reference with a reason" to your PR checklist. The toolkit has a PR review checklist and a production readiness checklist to extend.
• Turn on Dependabot, CodeQL and push protection on day one of a repository, not after the first incident.
• Look up any unfamiliar term in the glossary.

🧪 Try it yourself (optional, ~30 min)

1. Locally, two users: start everything with cd sample and aspire run. In a second terminal, create two tokens: bash cd sample dotnet user-jwts create --project src/Ledgerly.Api --name alice dotnet user-jwts create --project src/Ledgerly.Api --name bob Open src/Ledgerly.Api/Ledgerly.Api.http, set @api to the API URL from the dashboard and @token to Alice's token. Create a portfolio and copy its id from the Location header.
2. Switch @token to Bob's token and request GET {{api}}/api/portfolios/<alice's id>. You get 404. List portfolios as Bob: the list is empty.
3. Remove the Authorization header and send the list request again. You get 401.
4. Locally, no Azure: from cd sample, run bicep build infra/main.bicep --stdout and search the output for password and Active Directory. The only password= sits inside the Redis expression that writes straight into Key Vault. Active Directory Managed Identity shows up in both SQL connection strings: the apps' and the migration job's.
5. 🧪 With Azure: after a deployment, run the two commands from the helpers. Match each role assignment to an arrow in the "who can reach what" diagram, and confirm disableLocalAuth is true.

   🧪 Not run by the author: this step was written from the docs and validated with bicep build only. Expect small differences.

✅ Recap

1. Managed identities replace passwords and keys for every Ledgerly arrow into Azure (SQL, Service Bus, KEDA, the registry and Key Vault), and disabling local auth makes leaked keys worthless.
2. Use a deterministic credential in production (ManagedIdentityCredential with the client id, or the SQL Active Directory Managed Identity keyword) and keep DefaultAzureCredential for developer machines.
3. Users authenticate with JWT bearer tokens (user-jwts locally, Entra ID in Azure), every query filters by the owner's oid, and the few remaining secrets live in Key Vault while Dependabot, CodeQL and push protection guard the supply chain.

Next → Chapter 14: Reliability patterns

Chapter 14: Reliability patterns

⏱ About 30 min · You'll learn: what the standard resilience handler really does with its defaults, how to degrade gracefully and wire health probes without restarting healthy replicas, and how idempotency, EF retries, rate limits and bulkheads stop one failure from becoming many.

📖 Story: Priya flips the switch

It is demo day. Elena has invited two advisors to see the beta build, and you are driving. You open a portfolio, click Valuation, and the numbers appear in a few hundred milliseconds. Elena nods. Then Priya, sitting at the back with her laptop, says "one second" and types something. You refresh. The spinner turns, and keeps turning. After about fifteen seconds the page fills in: holdings and cost basis are there, but every price says "unavailable" and the total market value is empty.

"I set the market-data failure rate to 100%," Priya says. "That's what happens when the vendor goes down at 9 a.m. on a Monday." Elena asks the question she always asks: "What does the user see?" Priya answers honestly: "A spinner for fifteen seconds, then half a page. That's better than a 500. It's not good enough."

Afterwards Maya pulls you into a room. "At Nordbank, how did you handle the flaky SOAP vendor?" You admit it: a for loop, Thread.Sleep(1000), three attempts, and a WCF sendTimeout nobody remembered setting. She smiles. "Same instinct, better tools. Let's see what's already protecting us, and what those fifteen seconds are made of." You open your notebook to Habits I brought with me and write: "Retry in a loop with Thread.Sleep."

Numbers in the Ledgerly story (latency, request counts, timings) are illustrative. The resilience defaults quoted from the docs are real and marked 🔧.

🏚️ Old way → 🚀 New way

💡 Reliability is not about preventing failure. It is about deciding, in advance, what happens when each dependency fails.

🧠 The failures you design for

Before choosing patterns, name the failures. Maya keeps this table on the team wiki, and each row is a question for every new dependency.

The first four are about calls, the last three are about work. Chapter 7 covered the work side in depth (outbox, dead-letter, graceful shutdown). This chapter connects both sides and adds the HTTP pipeline, probes and limits.

💡 A retry is a bet that the next attempt will succeed. It is a good bet for transient errors and a terrible bet for outages and overload.

🧠 The standard resilience handler, defaults and all

The package Microsoft.Extensions.Http.Resilience 🔧 is built on Polly v8. One call, AddStandardResilienceHandler(), wraps every outgoing HttpClient request in a pipeline of five strategies. The older Microsoft.Extensions.Http.Polly (AddPolicyHandler, Polly v7) is deprecated, so if you find it in old code, migrate.

Source: Build resilient HTTP apps.

💻 In Ledgerly: one line for every HttpClient

📄 sample/src/Ledgerly.ServiceDefaults/Extensions.cs

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            // Retries with jittered back-off, per-attempt + total timeouts, circuit breaker, rate limiter.
            http.AddStandardResilienceHandler();

            // Resolves "https+http://marketdata" to a real address (Aspire locally, config or DNS in Azure).
            http.AddServiceDiscovery();
        });

ConfigureHttpClientDefaults applies to every client created by IHttpClientFactory in that service, including the typed MarketDataClient. The client itself stays boring on purpose:

📄 sample/src/Ledgerly.Core/Market/MarketDataClient.cs

/// <summary>
/// Typed HttpClient for the market-data service. Base address, retries, timeouts and the circuit breaker
/// are configured at registration time (see ServiceDefaults), not here. This class just speaks HTTP.
/// </summary>
public sealed class MarketDataClient(HttpClient http) : IMarketDataClient
{
    // ...
        var quotes = await http.GetFromJsonAsync<Quote[]>($"/prices?symbols={query}", cancellationToken) ?? [];
    // ...
}

No retry loop, no timeout constant, no try/catch. Policy lives in one place, code lives in another. That separation is the biggest change from the Thread.Sleep habit.

What the defaults did during the demo

Now you can explain Priya's fifteen seconds:

1. Every call to /prices got a 503 from the chaos switch.
2. The retry strategy treated 503 as transient and tried again three times, waiting a little longer each time (starting around 2 s, growing exponentially, with jitter). Those waits add up to roughly the fifteen seconds you saw.
3. The circuit breaker never opened. It needs at least 100 calls in its 30-second sampling window before it judges the failure ratio. A demo with three people clicking produces a handful of calls.
4. After the last retry, the handler returned the final 503, GetFromJsonAsync threw HttpRequestException, and the valuation degraded (next section).

Point 3 is the one that surprises people. The defaults are tuned for services with real traffic. At beta volume, the breaker protects you only when many users hit the outage at once. In production with real load, the breaker opens after enough failures, every call fails immediately with BrokenCircuitException for 5 seconds, and the page degrades in milliseconds instead of seconds.

flowchart LR
    App["ValuationService<br/>calls MarketDataClient"] --> RL["1 Rate limiter<br/>1,000 concurrent"]
    RL --> TT["2 Total timeout<br/>30 s"]
    TT --> RT["3 Retry<br/>3 times, backoff + jitter"]
    RT --> CB["4 Circuit breaker<br/>10% of at least 100 calls"]
    CB --> AT["5 Attempt timeout<br/>10 s"]
    AT --> MD["MarketData<br/>/prices"]
    CB -- "open: fail fast" --> X["BrokenCircuitException"]
    TT -- "budget spent" --> Y["TimeoutRejectedException"]

Tuning it for a user-facing call

For a valuation screen, fifteen seconds is too long. You can tune the standard handler with an options callback:

// illustrative, not in the sample
http.AddStandardResilienceHandler(options =>
{
    options.Retry.MaxRetryAttempts = 2;
    options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(3);
    options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(8);
});

Two rules keep tuning safe. Keep the total timeout shorter than your caller's patience (the browser, Leo's SPA, or an upstream service). And change the pipeline in one place: adding a second AddStandardResilienceHandler() on a typed client that already gets one from ConfigureHttpClientDefaults stacks two pipelines, and the retries multiply.

For non-HTTP work (a database call, a file share, an SDK without built-in retries), Microsoft.Extensions.Resilience gives you the same building blocks with AddResiliencePipeline("name", ...).

💡 The defaults are a good starting point, not a design. Read them, do the math for your traffic, and tune the call paths that users wait on.

🧠 Graceful degradation, timeouts and cancellation

Retries and breakers decide when to give up. Degradation decides what to return when you do. Ledgerly's valuation has two parts: the holdings and cost basis come from your own database, the prices come from the vendor. If the vendor is down, half the answer is still true.

💻 In Ledgerly: a partial valuation instead of a 500

📄 sample/src/Ledgerly.Api/Services/ValuationService.cs

    private async Task<decimal?> GetPriceAsync(string symbol, CancellationToken ct)
    {
        try
        {
            return await cache.GetOrCreateAsync(
                $"quote:{symbol}",
                async token =>
                {
                    var quotes = await marketData.GetQuotesAsync([symbol], token);
                    return quotes.TryGetValue(symbol, out var q) ? q.Price : (decimal?)null;
                },
                tags: ["quotes"],
                cancellationToken: ct);
        }
        catch (Exception ex) when (ex is HttpRequestException or BrokenCircuitException or TimeoutRejectedException)
        {
            LogPriceUnavailable(logger, symbol, ex.GetType().Name);
            return null;
        }
    }

And in GetAsync:

        var complete = lines.All(l => l.Price is not null);
        return new PortfolioValuation(
            portfolio.Id,
            portfolio.BaseCurrency,
            lines,
            lines.Sum(l => l.CostBasis),
            complete ? lines.Sum(l => l.MarketValue!.Value) : null,
            complete,
            clock.GetUtcNow());