
<Sponsorships>

AI agents don't have an intelligence problem, they have a context problem.
[**Redis Iris**](https://fandf.co/4akmLsn) is a real-time context engine that transforms fragmented data into live, agent-ready context and memory.
Feed your agents the right data, in the right form, at the right time.
[**Try for free today**](https://fandf.co/4akmLsn).

[**Build and ship at the Runpod Flash Hack Day**](https://dub.sh/iVPwW9o)!
Join Runpod on June 30 at the SF Builder's Collective for an in-person hackathon.
Remote-friendly.
Learn how to use Runpod Flash to turn Python functions into auto-scaling, serverless GPU endpoints without Docker.
Demos, prizes, and mentorship.
[**Register here**](https://dub.sh/iVPwW9o).

</Sponsorships>

Most real business processes don't finish in a single request.

An order gets placed, inventory gets checked, a payment gets charged, stock gets reserved, and the customer gets notified.
Each step can fail, time out, or need a retry.
And the whole thing has to survive a process restart without losing its place or charging someone twice.

We usually solve this with a pile of queues, a state table, and a lot of defensive code to track where each process is.
It works, but the business logic ends up scattered across handlers and database rows, and nobody can read the flow top to bottom anymore.

[**Dapr**](introduction-to-dapr-for-dotnet-developers) (a graduated [CNCF](https://www.cncf.io/) project) has a building block for exactly this: **Workflow**.
You write the process as ordinary C# code, and Dapr makes it durable.
If the host crashes halfway through, the workflow picks up right where it left off.

In this article, we'll build a small Dapr Workflow, run it with [**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development), and inspect its state with the [**Diagrid Dev Dashboard**](https://docs.diagrid.io/develop/local-development/dev-dashboard/?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows).
If you'd rather learn this hands-on, there's also a free [**Dapr University track**](https://www.diagrid.io/dapr-university/dapr-workflows-dotnet-aspire?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows) built around this exact stack.

Let's dive in.

## What Dapr Workflow Actually Is

You define a **workflow** that orchestrates a process, and **activities** that do the actual work (call a database, hit an API, send an email).
This is [**orchestration**](orchestration-vs-choreography) rather than choreography: one place drives the process instead of services reacting to each other's events.

The definitions live in your app; the **workflow engine** that executes them runs in the Dapr sidecar:

<figure>
  <Image
    src="/blogs/mnw_198/workflow-overview.png"
    width={1880}
    height={840}
    alt="Diagram of a workflow app containing workflow and activity definitions, communicating over the Dapr API (HTTP/gRPC) with the Dapr Workflow engine running in the sidecar."
  />
  <figcaption>
    Source: [Dapr - Workflows
    overview](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/)
  </figcaption>
</figure>

The key idea is **durable execution**.
Dapr records every step to a state store, so the workflow can be replayed from history at any time.
A crash, a deployment, or a scale-out event doesn't lose progress, and a workflow can run for seconds or for months.

One rule follows from this: **workflow code must be deterministic**.
No `DateTime.Now`, no random values, no I/O - anything non-deterministic goes into an _activity_.
Even logging is affected: use `context.CreateReplaySafeLogger<T>()` inside a workflow, or every replay will repeat your log lines.

Under the hood, this all runs on Dapr actors, which is why the state store must support actors. More on that in a moment.

## Building the Workflow

The quickest starting point is the [**Aspire CLI's**](https://aspire.dev/) starter template:

```bash
aspire new aspire-starter -n OrderProcessing
```

It generates the app host, an API service, and a `ServiceDefaults` project that wires up OpenTelemetry and health checks (that's where the `AddServiceDefaults` call comes from later).
If you're on Claude Code, the [**Dapr Skills**](https://github.com/diagrid-labs/dapr-skills) plugin can scaffold the entire workflow project from a prompt and review it for determinism mistakes.
Everything we build here is also in a [**working sample on my GitHub**](https://github.com/m-jovanovic/dapr-workflows-with-aspire), so you can clone it and follow along.

The API service needs the `Dapr.Workflow` package:

```xml
<PackageReference Include="Dapr.Workflow" Version="1.18.1" />
```

A workflow derives from `Workflow<TInput, TOutput>` and reads top to bottom like a normal method, even though every step is durably persisted:

```csharp
using Dapr.Workflow;

namespace OrderApi.Workflows;

internal sealed class OrderProcessingWorkflow : Workflow<OrderPayload, OrderResult>
{
    public override async Task<OrderResult> RunAsync(
        WorkflowContext context,
        OrderPayload order)
    {
        // 1. Check inventory
        var inventory = await context.CallActivityAsync<InventoryResult>(
            nameof(CheckInventoryActivity),
            order);

        if (!inventory.InStock)
        {
            return new OrderResult(order.OrderId, "Rejected: out of stock");
        }

        // 2. Charge the customer
        await context.CallActivityAsync(
            nameof(ProcessPaymentActivity),
            new PaymentRequest(order.OrderId, order.TotalAmount));

        // 3. Reserve the stock
        await context.CallActivityAsync(
            nameof(UpdateInventoryActivity),
            order);

        // 4. Notify the customer
        await context.CallActivityAsync(
            nameof(NotifyCustomerActivity),
            order.CustomerId);

        return new OrderResult(order.OrderId, "Completed");
    }
}
```

`CallActivityAsync` doesn't invoke the activity directly.
It schedules the work with the workflow engine, which records the result once the activity completes.
If the process dies after the payment step, Dapr replays the workflow, feeds it the recorded results for completed steps, and resumes at the inventory update.
The customer never gets charged twice.

This is the **task chaining** pattern.
Dapr Workflow also supports fan-out/fan-in, external events, timers, and child workflows - all in plain C# (fan-out is just `Select` plus `Task.WhenAll`).
If you want to build the richer patterns hands-on, the free [**Build Dapr Workflows in .NET with Aspire**](https://www.diagrid.io/dapr-university/dapr-workflows-dotnet-aspire?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows) track has you fan out to parallel activities and aggregate the results.

One production caveat: the recorded history is tied to the shape of your code, so changing a workflow while instances are in flight breaks their replay.
That's solved with [**workflow versioning**](https://www.diagrid.io/blog/how-to-version-net-workflows?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows); we're staying on version one here.

An activity is where the real work happens, and the only place you're allowed to be non-deterministic.
It derives from `WorkflowActivity<TInput, TOutput>` and supports constructor injection:

```csharp
using Dapr.Workflow;

namespace OrderApi.Activities;

internal sealed class CheckInventoryActivity(IInventoryService inventory)
    : WorkflowActivity<OrderPayload, InventoryResult>
{
    public override async Task<InventoryResult> RunAsync(
        WorkflowActivityContext context,
        OrderPayload order)
    {
        bool inStock = await inventory.HasStockAsync(order.ProductId, order.Quantity);

        return new InventoryResult(inStock);
    }
}
```

The other activities follow the same shape: charge the card, decrement stock, send the confirmation email.
Each one is isolated, so Dapr can retry a failed activity without re-running the whole workflow.
And since every input and output gets serialized to the state store, simple JSON-friendly records are the right tool for these types.

## Starting Workflows Over HTTP

Register the workflow and its activities in the API service's `Program.cs`:

```csharp
builder.Services.AddDaprWorkflow(options =>
{
    options.RegisterWorkflow<OrderProcessingWorkflow>();

    options.RegisterActivity<CheckInventoryActivity>();
    options.RegisterActivity<ProcessPaymentActivity>();
    options.RegisterActivity<UpdateInventoryActivity>();
    options.RegisterActivity<NotifyCustomerActivity>();
});
```

This also registers a `DaprWorkflowClient` we can use to start and query workflow instances:

```csharp
app.MapPost("/orders", async (
    OrderPayload order,
    DaprWorkflowClient workflowClient) =>
{
    string instanceId = await workflowClient.ScheduleNewWorkflowAsync(
        name: nameof(OrderProcessingWorkflow),
        instanceId: order.OrderId,
        input: order);

    return Results.Accepted($"/orders/{instanceId}", new { instanceId });
});

app.MapGet("/orders/{instanceId}", async (
    string instanceId,
    DaprWorkflowClient workflowClient) =>
{
    WorkflowState? state = await workflowClient.GetWorkflowStateAsync(instanceId);

    if (state is null || !state.Exists)
    {
        return Results.NotFound();
    }

    return Results.Ok(new
    {
        RuntimeStatus = state.RuntimeStatus.ToString(),
        Output = state.ReadOutputAs<OrderResult>()
    });
});
```

`ScheduleNewWorkflowAsync` returns immediately and the workflow runs in the background.
It's the same idea as [**scaling long-running API requests**](how-to-scale-long-running-api-requests): return `202 Accepted` and let the client poll for status.
Two SDK quirks worth knowing: `GetWorkflowStateAsync` returns `null` for an instance it has never seen, and `RuntimeStatus` is an enum that serializes as a bare number without the `ToString()`.

## Running Everything With Aspire

Here's where Aspire earns its keep.
A Dapr Workflow needs a sidecar and a state store running alongside the app, and Aspire orchestrates all of it from one place.

<figure>
  <Image
    src="/blogs/mnw_198/workflow-app-aspire.png"
    width={977}
    height={581}
    alt="Architecture diagram: Aspire locally manages the workflow app and the Dapr sidecar with its workflow engine, which reads and writes workflow state to a state store. The Diagrid Dev Dashboard connects to the same state store to visualize workflow executions."
  />
  <figcaption>
    Source: [Dapr
    University](https://www.diagrid.io/dapr-university/dapr-workflows-dotnet-aspire?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows)
  </figcaption>
</figure>

The app host needs two packages.
The Dapr integration lives in the [**Aspire Community Toolkit**](https://learn.microsoft.com/en-us/dotnet/aspire/community-toolkit/overview) these days; the original `Aspire.Hosting.Dapr` package is deprecated.

```xml
<PackageReference Include="CommunityToolkit.Aspire.Hosting.Dapr" Version="13.0.0" />
<PackageReference Include="Aspire.Hosting.Valkey" Version="13.4.3" />
```

Then the app host:

```csharp
using CommunityToolkit.Aspire.Hosting.Dapr;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDapr();

// Pin the password. Aspire generates a random one on every run otherwise,
// and the Dapr component file below has to know it.
var statePassword = builder.AddParameter(
    "statestore-password", "state-store-123", secret: true);

// Valkey (a Redis fork) as the workflow state store
var statestore = builder
    .AddValkey("statestore", 16379, statePassword)
    .WithDataVolume();

builder.AddProject<Projects.OrderApi>("order-api")
    .WithDaprSidecar(new DaprSidecarOptions
    {
        ResourcesPaths = ["./Resources"]
    })
    .WaitFor(statestore);

builder.Build().Run();
```

`WithDaprSidecar` runs a Dapr sidecar next to `order-api`, and `ResourcesPaths` points it at the Dapr component files (relative paths resolve against the app host directory).

The one component the workflow needs is a state store - a `statestore.yaml` in the app host's `Resources` folder:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: workflowstore
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: 'localhost:16379'
    - name: redisPassword
      value: 'state-store-123'
    - name: actorStateStore
      value: 'true'
```

That `actorStateStore: "true"` line is the one people forget.
Dapr Workflow runs on top of actors, so without it, workflows won't run.
Notice the application never sees any of this: swapping Valkey for Postgres means editing this YAML file, not your C# code.

Install the [**Dapr CLI**](https://docs.dapr.io/getting-started/install-dapr-cli/) and run `dapr init` once (that's where the sidecar binary comes from), then start everything with a single command:

```bash
aspire run
```

Aspire spins up Valkey, the Dapr sidecar, and the API, with logs, traces, and health in one dashboard.
Grab the API's port from there and post an order:

```bash
curl -X POST http://localhost:5555/orders \
  -H "Content-Type: application/json" \
  -d '{"orderId":"order-001","customerId":"cust-42","productId":"pro-plan","quantity":2,"totalAmount":49.99}'
```

Poll the status endpoint and you'll see the workflow march through its activities (if the first request returns a `500`, give the sidecar a few more seconds to connect to the placement service):

```bash
curl http://localhost:5555/orders/order-001
```

```json
{
  "runtimeStatus": "Completed",
  "output": {
    "orderId": "order-001",
    "status": "Completed"
  }
}
```

Each activity shows up as a span in the distributed trace:

<Image
  src="/blogs/mnw_198/aspire_distributed_trace_order_creation.png"
  width={1919}
  height={1079}
  alt="Aspire dashboard distributed trace for POST /orders, showing the workflow orchestration span and individual spans for the CheckInventory, ProcessPayment, UpdateInventory, and NotifyCustomer activities."
/>

## Inspecting Workflow State Locally

The Aspire dashboard shows you the request flow, but not the _workflow's_ internal state: which step it's on, what each activity returned, and the full execution history.
For that, there's the [**Diagrid Dev Dashboard**](https://docs.diagrid.io/develop/local-development/dev-dashboard/?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows): a free, local-only tool that reads your workflow state store (Redis-compatible, Postgres, or SQLite) and visualizes every instance.
It comes from Diagrid, the company founded by the creators of the Dapr OSS project, which also provides enterprise Dapr support.

Since the whole point of this setup is that one command starts everything, let's add it to the app host:

```csharp
builder.AddContainer("diagrid-dashboard", "ghcr.io/diagridio/diagrid-dashboard:latest")
    .WithBindMount("./Resources", "/app/components")
    .WithEnvironment("COMPONENT_FILE", "/app/components/dashboard-store.yaml")
    .WithEnvironment("APP_ID", "diagrid-dashboard")
    .WithHttpEndpoint(targetPort: 8080)
    .WaitFor(statestore);
```

Why a second component file? Networking.
The sidecar runs as a host process, so `localhost:16379` works for it.
The dashboard runs in a container, where `localhost` means the container itself, so its `dashboard-store.yaml` reaches the host through `host.docker.internal`
(on Linux without Docker Desktop, use the bridge gateway IP instead):

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: dashboardstore
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: 'host.docker.internal:16379'
    - name: redisPassword
      value: 'state-store-123'
    - name: actorStateStore
      value: 'true'
scopes:
  - diagrid-dashboard
```

The `scopes` field keeps the API's sidecar from picking up this component, since both files sit in the same `Resources` folder.

Run `aspire run` again and open the dashboard's endpoint from the Aspire resources view.
Every workflow instance is listed with its status, app ID, and duration:

<Image
  src="/blogs/mnw_198/diagrid_dashboard_workflows.png"
  width={1919}
  height={1079}
  alt="Diagrid Dev Dashboard listing OrderProcessingWorkflow executions with their status, instance ID, app ID, and start and end times."
/>

Clicking an instance shows the exact input the workflow received and the output it produced:

<Image
  src="/blogs/mnw_198/diagrid_dashboard_workflow_instance.png"
  width={1918}
  height={1079}
  alt="Workflow Execution Details page showing a running OrderProcessingWorkflow instance with its status and input payload."
/>

Below that sits the full execution history - the ground truth of what your workflow actually did.
Expand a `TaskScheduled` event to see an activity's input, or a `TaskCompleted` event to see its input and output:

<Image
  src="/blogs/mnw_198/diagrid_dashboard_workflow_history.png"
  width={1919}
  height={1079}
  alt="Execution History table showing TaskScheduled and TaskCompleted events for each activity in the order processing workflow."
/>

Being able to see the workflow's actual state, not just guess at it from logs, is what makes local workflow development feel sane.
There's also a [`Diagrid.Aspire.Hosting.Dashboard`](https://www.nuget.org/packages/Diagrid.Aspire.Hosting.Dashboard) package that wraps this container setup into a single `AddDiagridDashboard` call.

## Summary

Dapr Workflow gives you durable execution for long-running processes without dragging a heavy orchestration engine into your code:

- The process is **plain C# code** that reads top to bottom.
- Dapr makes it **fault-tolerant**, replaying from the state store so a crash never loses progress.
- The orchestration stays **deterministic**; the side effects live in activities.
- **Aspire** runs the sidecar, the state store, and the dashboard with one command.
- The **Diagrid Dev Dashboard** shows you exactly what each instance is doing.

You can grab the complete [**source code for this article**](https://github.com/m-jovanovic/dapr-workflows-with-aspire) on my GitHub, including Aspire integration tests for the workflow.

If you want to go deeper, the free [**Build Dapr Workflows in .NET with Aspire**](https://www.diagrid.io/dapr-university/dapr-workflows-dotnet-aspire?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows) track on Dapr University is the natural next step.
You'll build a fan-out/fan-in workflow on this exact stack in a hosted sandbox, with nothing to install.
The [**Dapr Workflow track**](https://www.diagrid.io/dapr-university/dapr-workflow?utm_source=milanjovanovic&utm_medium=referral&utm_campaign=workflows) covers the remaining patterns in standalone examples.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**AWS Summit New York City**](https://bit.ly/4nT9Jb5) is back June 17 at Javits Convention Center.
Join developers, architects, and cloud leaders for 200+ sessions on AI, modernization, security, and cloud infrastructure.
[**Register for free**](https://bit.ly/4nT9Jb5).

[**AI chips keep getting faster**](https://fandf.co/4vsPWSk), but the infrastructure developers rely on hasn't kept up.
In this piece, [**Runpod**](https://fandf.co/4vsPWSk) (A.K.A the AI Developer Cloud) explores why the real bottleneck may be the stack around the hardware,
and what a developer first approach to AI infrastructure looks like.

</Sponsorships>

Every developer learns DRY early, and almost everyone learns it wrong.

Don't Repeat Yourself.
See two pieces of code that look the same, extract a method, delete the duplicate.
I did this for years and wrote some of the worst code I've ever had to maintain:

- A shared helper that grew a new boolean parameter every sprint.
- A base class nobody dared touch because six unrelated features inherited from it.
- A "common" module two independent parts of the system both depended on, so neither could change without the other.

Every one started as an innocent attempt to not repeat myself.

## What DRY Actually Says

Here's the part most people skip.
The original definition, from Andy Hunt and Dave Thomas in [_The Pragmatic Programmer_](https://en.wikipedia.org/wiki/The_Pragmatic_Programmer),
says nothing about code:

> Every piece of **knowledge** must have a single, unambiguous, authoritative representation within a system.

It's about knowledge. A single _fact_ about your domain, like a tax rule or the format of an invoice number,
should live in exactly one place.
When that fact changes, you change it once instead of hunting for seven copies.

## The Mistake: Deduplicating Code, Not Knowledge

Two pieces of code can look identical and represent completely different knowledge.

Say you validate two addresses.
One is a customer's shipping address, the other is a warehouse address.
Today the rules are identical:

```csharp
public bool IsValid(Address address) =>
    !string.IsNullOrWhiteSpace(address.Street) &&
    !string.IsNullOrWhiteSpace(address.City) &&
    !string.IsNullOrWhiteSpace(address.PostalCode);
```

The DRY reflex says extract one validator and call it from both places.
But these are different concepts that happen to share rules this week.
The day the warehouse needs a loading-dock code,
you're back in the shared method bolting on a flag to keep the other caller working:

```csharp
public bool IsValid(Address address, bool requireDockCode = false) =>
    !string.IsNullOrWhiteSpace(address.Street) &&
    !string.IsNullOrWhiteSpace(address.City) &&
    !string.IsNullOrWhiteSpace(address.PostalCode) &&
    (!requireDockCode || !string.IsNullOrWhiteSpace(address.DockCode));
```

That boolean is the tell.
The first time a shared method grows a flag so one caller behaves differently, you didn't have duplication.
You had two things that looked alike and glued them together.
Give it a year and the signature has three more flags,
each one a place where the two concepts were never actually the same.

## The Wrong Abstraction Costs More Than Duplication

**Duplication is far cheaper than the wrong abstraction**.

Copy-paste is visible and local.
You can see both copies, and if they drift apart, that was always allowed.
The wrong abstraction is invisible and global.
Every caller depends on one shape and bends it to fit, the flags pile up,
and you end up afraid to touch a method you no longer understand.
I've spent more time deleting bad abstractions than I ever saved writing them.

This is the [**hidden coupling cost I wrote about in the abstractions piece**](the-real-cost-of-abstractions-in-dotnet),
and DRY-by-reflex is one of the most common ways it sneaks in.

## Where It Hurts Most: Across Boundaries

Inside one class, a bad helper is annoying. Across module boundaries, it's structural damage.

Picture a [**modular monolith**](what-is-a-modular-monolith) with a `Billing` module and a `Shipping` module.
Both have an `Order`.
A well-meaning engineer notices the two classes share fields and pulls them into a shared type both modules reference:

```csharp
// Shared.Orders, referenced by both Billing and Shipping
public class Order
{
    public Guid Id { get; set; }
    public string CustomerName { get; set; }
    public decimal Total { get; set; }
    // ...whatever either module happens to need
}
```

Now Billing and Shipping can't evolve independently.
A change to billing's order forces a recompile, re-test, and redeploy of shipping.
You took two bounded contexts that were supposed to be decoupled and welded them together to save a few properties.

Two modules each owning their own `Order` is the whole point of [**keeping data inside its boundaries**](how-to-keep-your-data-boundaries-intact-in-a-modular-monolith). The shapes are allowed to be similar, modeling the same real-world thing from two points of view that drift over time. It's the same reason [**vertical slices**](vertical-slice-architecture-is-easier-than-you-think)
tolerate a little repetition, so each slice can change on its own.

## The Rule I Use: Wait for the Third Time

I don't deduplicate the second time I see something.
I wait for the third, and I ask one question: if this rule changes, do both copies have to change together?

- **Yes** - it's real duplication, the same fact written in several places. Extract it, and that's DRY doing its job.
- **No** - the resemblance is a coincidence. Leave it alone, and coupling them will cost you later.

Let the code repeat until the right abstraction becomes obvious,
because good abstractions are discovered from concrete cases, not guessed up front.
Some people call this AHA, for "Avoid Hasty Abstractions."

A practical tell: extract when you can name the concept.
A real domain name like `Money`, `TaxRate`, or `InvoiceNumber` is probably knowledge worth a [**value object**](value-objects-in-dotnet-ddd-fundamentals).
If the best name you can find is `Helper`, `Utils`, or `ProcessData`, you're abstracting shape, not knowledge.

## When DRY Is Right

Applied correctly, DRY is invaluable.
A business rule belongs in exactly one place.
Watch what happens when "an order over $1,000 needs manager approval" gets copy-pasted across three services:

```csharp
// OrderService
if (order.Total > 1000) { /* require approval */ }

// CheckoutService
if (order.Total > 1000m) { /* require approval */ }

// AdminController - someone bumped the limit here, and only here
if (order.Total > 5000) { /* require approval */ }
```

You will eventually update two of them and ship a bug.
That drifted third copy is exactly how it happens.
Push the rule into the [**domain model**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model) where it has one home:

```csharp
public bool RequiresManagerApproval() => Total > 1000;
```

That's the single authoritative representation DRY is actually about.

## Summary

- DRY is about **knowledge**, not code that looks alike.
- The wrong abstraction costs more than the duplication it replaced, and it's harder to undo.
- Wait for the third occurrence. Extract only when both copies encode the same fact and must change together.

The next time you're about to delete a duplicate, don't ask whether the code looks the same.
Ask whether it _means_ the same.
That one question will save you more maintenance pain than DRY ever saved you typing.

If you want to see how I draw these boundaries in a real system,
with independent modules and abstractions that earn their place, that's the heart of [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).

Thanks for reading.

And stay awesome!

---



<Sponsorships>

With [**Coder Agents**](https://fandf.co/43EZ9Le), you can run tasks in a system you already trust.
No API keys, no agent harnesses, and no special software, delegate development and research within a single control plane.
[**Learn more here**](https://fandf.co/43EZ9Le).

[**Sonar's acquisition of Gitar**](https://fandf.co/4aiWvP4) will allow the company to deliver code review from the moment
an agent starts writing code to the moment it lands in the codebase.
Gitar adds an [**AI-native code review layer**](https://fandf.co/4aiWvP4) on top of SonarQube's multilayered code verification platform—flagging issues,
generating the fix, validating it against the CI, and committing to the branch only when the build passes.
The result: fewer production surprises from AI-generated code that technically passed inspection.

</Sponsorships>

Every backend developer eventually hits the same wall: a method that can return _one of several things_.

A parse that either gives you a number or an error.
A lookup that returns a value or "not found".
An operation that succeeds or fails.
In C#, we've never had a clean way to model "this is an `A` **or** a `B`".
So we faked it - with marker interfaces, abstract base classes, tuples, nullable returns, exceptions,
or the excellent [**OneOf**](https://github.com/mcintyre321/OneOf) library.

C# 15 (shipping with .NET 11) finally adds **union types** to the language.
I've wanted this for years, so let me give you a quick tour.

Let's dive in.

## The Problem

Say a method can return a user or fail because they don't exist. Today you'd reach for something like this:

```csharp
// Throw for the "failure" case - control flow via exceptions
public User GetUser(int id) =>
    _users.TryGetValue(id, out var user)
        ? user
        : throw new UserNotFoundException(id);
```

The signature says it returns a `User`, but that's a lie - it might throw instead. The caller has no way to know that without reading the body. The other usual workarounds (a bool `TryGet` with an `out` parameter, a custom `Result` class with nullable fields, or a `OneOf<User, NotFound>`) all add ceremony to express one simple idea.

What you actually want is a **closed set** of types. That's exactly what a union is.

## Declaring a Union

The syntax is delightfully small. You list a name and the case types:

```csharp
public union Result<T>(T, Exception);
```

That's it. A `Result<T>` is now _either_ a `T` _or_ an `Exception` - and nothing else. The types don't even need to be related, which is the whole point.

Here's a more concrete example with unrelated record types:

```csharp
public record CreditCard(string Last4, string Brand);
public record PayPal(string Email);
public record BankTransfer(string Iban);

public union PaymentMethod(CreditCard, PayPal, BankTransfer);
```

## Creating Values

There's an implicit conversion from each case type, so you just assign the value directly:

```csharp
PaymentMethod method = new CreditCard("4242", "Visa");
```

Try to assign a type that isn't in the set, and it's a **compile error**. The set is closed.

## Consuming a Union

This is where it shines. Pattern matching just works, and the compiler checks the inner value for you:

```csharp
string Describe(PaymentMethod method) => method switch
{
    CreditCard card  => $"{card.Brand} ending {card.Last4}",
    PayPal paypal    => $"PayPal ({paypal.Email})",
    BankTransfer ach => $"Bank transfer to {ach.Iban}",
}; // No `_` or `default` needed
```

Notice there's **no discard `_` and no `default` arm**. Because the union is closed, the compiler knows all three cases are covered. Forget one, and you get a warning at compile time:

```
warning CS8509: The switch expression does not handle all possible values
of its input type (it is not exhaustive). For example, the pattern 'BankTransfer'
is not covered.
```

That exhaustiveness check is the feature I'm most excited about. Add a new case to the union later, and the compiler points you at every `switch` you forgot to update.

## Back to The Problem

Remember our lying `GetUser` method from earlier? Let's fix it with a union.

First, declare what the method can actually return - a `User` or a `NotFound`:

```csharp
public record NotFound(int Id);

public union UserResult(User, NotFound);
```

Now the signature tells the truth, and there are no exceptions for control flow:

```csharp
public UserResult GetUser(int id) =>
    _users.TryGetValue(id, out var user)
        ? user
        : new NotFound(id);
```

And the caller has to handle both outcomes - the compiler won't let them forget:

```csharp
IResult response = GetUser(42) switch
{
    User user      => Results.Ok(user),
    NotFound found => Results.NotFound($"No user with id {found.Id}"),
};
```

That's the whole pitch. The return type _tells you the truth_: here are exactly the shapes you'll get back, and you can't ignore one by accident. No more reading the method body to discover what it might throw.

## A Few Caveats

This is still a **preview/experimental** feature. A few things to keep in mind:

- It targets **C# 15 / .NET 11**, and the syntax may still change before release. Try it on .NET 11 Preview 4 or later.
- Under the hood, a union is compiled to a `struct` that boxes value-type cases and stores the contents as a single `object?`. There's a non-boxing path for performance-sensitive code, but the default is simple.
- This is a _type_ union (an `A` or a `B`), not a full discriminated union with named cases yet. It covers the vast majority of what I reach for OneOf for today.

## Summary

Union types close a gap that's been open in C# for a very long time.

- Declare a **closed set** of types with `public union Name(A, B, C);`.
- Assign case values **directly** - implicit conversions handle the rest.
- **Pattern match** with full compiler-checked exhaustiveness, no `default` arm required.
- Model results, options, and "one of these" returns **without** marker interfaces, base classes, or extra libraries.

It's a small syntax with a big payoff: your method signatures finally tell the truth about what they return, and the compiler keeps every `switch` honest.

I'll explore this feature more in the future, but I wanted to share this quick tour now that it's available in preview.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

Secure your "vibe-coded" app before a high traffic spike breaks it.
[**Leverage Redis Cloud for ultra-low latency**](https://fandf.co/42JvccM), application-layer rate limiting to block brute-force attempts and mitigate DDoS surges.
[**Explore Redis Cloud and start for free today**](https://fandf.co/42JvccM) to keep your backend protected and resilient under pressure.
Use the code MILAN100 for $100 in free credits.

Most cloud migration plans stall in the planning phase.
Microsoft's new [**Azure Copilot Migration Agent**](https://fandf.co/4dsafJA) generates one automatically from your VMware inventory,
compares lift-and-shift against modernization, and hands landing zone templates to GitHub Copilot.
It's one of six Copilot agents now covering the full Azure ops cycle.
The free Introduction to Azure Copilot Agents module on MS Learn walks through each. Check it out.
[**Start the free module**](https://fandf.co/4dsafJA).

</Sponsorships>

Every system I've worked on eventually grows an endpoint that takes minutes to finish (or longer).
A report that aggregates years of data. A bulk import. A workflow that fans out to three external services and a database before it can answer.

You end up with two problems at once.
Your users sit on a spinner for several minutes, and your API holds that request open the entire time - burning a thread, a connection, and a slot in your concurrency budget.
A small traffic spike on that one endpoint could potentially take the rest of the API down with it.

I want to walk through the progression I use to fix this.
It's the same path the diagram below traces, from "the request just blocks" to a fully decoupled,
queue-backed worker pool - the shape I usually call an [**async API**](building-async-apis-in-aspnetcore-the-right-way).

Depending on your requirements, you might stop at any point along the way - but I want to make sure you understand the full path and the trade-offs at each step.

<Image
  src="/blogs/mnw_195/scaling_long_running_requests.png"
  width={5144}
  height={2263}
  alt="System design progression for scaling long-running API requests, from synchronous request to queue-based competing consumers."
/>

## Step 0: The Naive Version

A user sends a request. The application server does the work. The work takes five minutes. The connection stays open the whole time.

There is nothing _wrong_ with this approach - it's just paying for correctness with availability.
The user experience is bad, and the blast radius is large: every long request you accept is a request you _can't_ accept somewhere else.

The first realization you need to internalize is that **the response time and the work duration don't have to be the same thing**.

<div className="centered">
  <Image
    src="/blogs/mnw_195/blocking_api_request.png"
    width={1808 * 0.25}
    height={749 * 0.25}
    alt="Diagram of a blocking API request, where the user sends a request and waits for the work to finish before getting a response."
  />
</div>

## Step 1: Accept the Work, Don't Do It

The first move is to stop doing the work inside the request.

I add a `jobs` table that represents the work I _intend_ to do. The API endpoint now does three things:

1. Validate the request.
2. Insert a row into `jobs` with status `Pending`.
3. Return `202 Accepted` with a job ID.

A [**background processor**](running-background-tasks-in-asp-net-core) running inside the same API picks up `Pending` rows and works through them.
The client either polls a `GET /jobs/{id}` endpoint or - better - I push updates via [**SignalR**](adding-real-time-functionality-to-dotnet-applications-with-signalr),
[**Server-Sent Events**](server-sent-events-in-aspnetcore-and-dotnet-10), or email when the job is done.

<Image
  src="/blogs/mnw_195/202_accepted_background_processor.png"
  width={3354}
  height={1215}
  alt="Diagram of an API request that accepts work and returns 202, with a background processor that picks up pending jobs and processes them asynchronously."
/>

This already buys you a lot.
The endpoint returns in milliseconds, the user gets a job ID they can track, and a spike of incoming requests just becomes a spike of rows in a table.
That table is cheap to write to.

But there's a ceiling here, and it's easy to hit.

## Step 2: Decouple the Worker From the API

The background processor in Step 1 still lives inside your API process.
It competes for the same CPU, memory, and connection pool as your real endpoints.
If processing gets heavy or slow, your API starts feeling it - the very thing you were trying to avoid.

The fix is to pull the background processor out into its own deployable, and put a queue between the two.

The API now publishes a message to the queue (and optionally writes the job row for tracking).
A pool of background workers consumes from the queue and does the actual work - the same shape I covered in [**event-driven architecture with RabbitMQ**](event-driven-architecture-in-dotnet-with-rabbitmq).
This is the **competing consumers** pattern, and it gives you something the previous step couldn't: **independent scaling**.

<Image
  src="/blogs/mnw_195/scaling_long_running_requests_final.png"
  width={5144}
  height={1933}
  alt="System design progression for scaling long-running API requests, from synchronous request to queue-based competing consumers."
/>

Three things change once you cross this line:

- **The queue absorbs spikes.** Your API can keep accepting work at a constant rate while the workers drain at their own pace.
- **You scale workers separately from the API.** More throughput on background jobs doesn't mean more API instances.
- **Failures become normal.** A worker crash is just a message that goes back on the queue, not a 500 to your user.

You also get retryability, pause/resume, structured error handling, and a **dead-letter queue** for poison messages - effectively for free, because the queue infrastructure already provides them.

## What This Costs You

I'd be lying if I said this was a free upgrade.

You're now running a queue, a worker fleet, and a notification path. That's more moving parts to deploy, monitor, and alert on.
Your "is this done yet?" semantics are no longer obvious from the HTTP response - the client has to ask, or you have to tell them.
And every job needs to be [**idempotent**](the-idempotent-consumer-pattern-in-dotnet-and-why-you-need-it), because at-least-once delivery means your workers _will_ see duplicates.

If you only have one slow endpoint and modest traffic, this is overkill.
A simple "fire-and-forget with status polling" inside the same process is fine.
Don't reach for a queue until the pain justifies it.

## When I'd Use a Cloud Service Instead

You don't always need to assemble this from parts. A few alternatives I would consider:

- [**AWS SQS**](complete-guide-to-amazon-sqs-and-amazon-sns-with-masstransit) **+ Lambda** or [**Azure Service Bus**](messaging-made-easy-with-azure-service-bus) **+ Azure Functions** when I want the worker pool to scale to zero and I don't want to manage hosts.
- **Azure Durable Functions** or **AWS Step Functions** when the work is a multi-step workflow with timers, retries, and human approvals. Orchestration is what they're good at.
- [**Temporal**](https://temporal.io/) when the workflow is long-lived (hours, days) and I need first-class durable execution, versioning, and visibility across runs.

The trade-off is the usual one: less operational work, more vendor coupling, and a pricing model you need to model carefully when throughput grows.

## Summary

The progression is simple, and it generalizes:

1. **Don't do slow work inside the request.** Accept it, persist it, return `202`.
2. **Don't run workers inside the API.** Put a queue in between and scale the two sides independently.
3. **Tell the user when it's done.** Polling is fine, push is better.

This isn't a microservices argument. It's a separation between _accepting work_ and _doing work_ - two concerns that have very different scaling profiles and very different failure modes.

If you want the full implementation walkthrough, the [**video version is here**](https://youtu.be/U40HzU_KkDY).

Thanks for reading.

And stay awesome!

---



<Sponsorships>

Visual Studio's AI vendor lock-in is being challenged by JetBrains ReSharper.
Start testing our [**open AI ecosystem**](https://lp.jetbrains.com/acp-in-resharper/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=acp-in-resharper)
today to choose the agents that actually work best for your .NET projects.
[**Learn more here**](https://lp.jetbrains.com/acp-in-resharper/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=acp-in-resharper).

[**Coder Agents**](https://fandf.co/3PpGfVp) is the self-hosted chat interface that lets you delegate tasks without stepping outside your existing infrastructure.
With auditable access and strict network boundaries, you can run tasks in a system you already trust.
[**Check it out**](https://fandf.co/3PpGfVp)!

</Sponsorships>

One of the recurring bugs I've chased over the years is the "duplicate charge" support ticket.

The customer was charged once, but our system thought the payment had failed.
The payment provider had taken the money, the order had rolled back to a draft state, and the user had received a "Payment failed, please retry" email on top of it.
A single user action left every subsystem with a different opinion about what actually happened.

A use case looks like a transaction because it sits behind a single method call.
But the moment it touches more than one system, you are dealing with **partial failure**.

Here's how I think about it:

- The three categories every side effect falls into
- How to design use cases that fail loudly and recover safely
- When to reach for the [**Outbox pattern**](implementing-the-outbox-pattern) and when not to

Let's dive in.

## The Code That Looks Fine

Here's a typical "place an order" use case.
I've written this exact shape a hundred times, and so have you.

```csharp {12,14,16}
internal sealed class PlaceOrder(
    IOrderRepository orders,
    IPaymentService payments,
    IEmailService emails,
    IUnitOfWork unitOfWork)
{
    public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
    {
        var order = Order.Create(request.CustomerId, request.Items);
        orders.Insert(order);

        await payments.ChargeAsync(order.Id, order.Total, ct);

        await emails.SendOrderConfirmationAsync(order.Id, ct);

        await unitOfWork.SaveChangesAsync(ct);
        return Result.Success();
    }
}
```

There are three side effects in this method, sitting behind what looks like a single transactional boundary, with no coordination between them.

If `SaveChangesAsync` throws _after_ `ChargeAsync` succeeded, you've taken the customer's money and lost the order.
If `SendOrderConfirmationAsync` throws, the order saves and the charge goes through, but no email is sent.
And if you naively retry, you double-charge.

The use case "works" until it doesn't, and when it doesn't, it tends to fail in a different way every time.

## Three Categories of Side Effect

Before you write a single line of recovery code, classify every side effect into one of three buckets:

1. **Transactional** - lives inside your database transaction. Inserts, updates, [**domain events**](how-to-use-domain-events-to-build-loosely-coupled-systems) dispatched in-process.
2. **External and reversible** - an API call you can compensate for. Charge → refund. Reserve inventory → release.
3. **External and irreversible** - sent emails, posted webhooks, SMS messages. Once they're out, they're out.

The category determines the strategy. There is no single "handle errors properly" rule that covers all three.

## Strategy 1: Pull Transactional Work to the End

The first move is mechanical.
Anything transactional should commit _last_, after all external calls have either succeeded or been explicitly tolerated.

```csharp {7,11}
public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
{
    var order = Order.Create(request.CustomerId, request.Items);

    var charge = await payments.ChargeAsync(order.Id, order.Total, ct);
    if (charge.IsFailure) return charge;
    order.MarkPaid(charge.Value.TransactionId);

    orders.Insert(order);

    await unitOfWork.SaveChangesAsync(ct);
    return Result.Success();
}
```

You can't always do this - sometimes you need a database ID before calling the external service.
That's fine.
The point isn't ordering for its own sake. It's making sure that if you commit, you've already done the work the commit promises.

## Strategy 2: Move Irreversible Side Effects Outside the Use Case

This is where the [**Outbox pattern**](scaling-the-outbox-pattern) earns its keep.

Instead of sending the email directly, raise an `OrderPlaced` [**domain event**](how-to-use-domain-events-to-build-loosely-coupled-systems) and let an outbox dispatcher pick it up _after_ the transaction commits.

```csharp {10,11}
public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
{
    var order = Order.Create(request.CustomerId, request.Items);

    var charge = await payments.ChargeAsync(order.Id, order.Total, ct);
    if (charge.IsFailure) return charge;
    order.MarkPaid(charge.Value.TransactionId);

    orders.Insert(order);
    order.Raise(new OrderPlacedEvent(order.Id));
    await unitOfWork.SaveChangesAsync(ct);

    return Result.Success();
}
```

The email is no longer the use case's problem.
If the transaction commits, the event commits with it inside the same write.
If it doesn't, the event never escapes the database and no email is ever sent.
A separate worker turns events into emails, with its own retries and its own [**idempotency**](the-idempotent-consumer-pattern-in-dotnet-and-why-you-need-it) guarantees.

## Strategy 3: Make External Calls Idempotent or Compensable

The payment call is the dangerous one.
If it succeeds and your transaction rolls back, you've taken money you can't account for.

What you do _not_ do is silently swallow the failure:

```csharp
try
{
    await payments.ChargeAsync(order.Id, order.Total, ct);
}
catch
{
    // shrug
}
```

The symptom disappears from your logs, the money stays gone, and the next time the user retries you charge them again.

There are two approaches I actually use, and they compose well together.

### Approach A: Idempotency Keys

Most serious payment providers (Stripe, Adyen, Braintree) let you attach an **idempotency key** to a charge.
A retry with the same key is a no-op on their side and returns the original result.
The natural key here is the order ID:

```csharp {6}
var charge = await payments.ChargeAsync(
    new ChargeRequest
    {
        OrderId = order.Id,
        Amount = order.Total,
        IdempotencyKey = order.Id.ToString()
    },
    ct);
```

Now it's safe to retry the use case.
If the previous attempt charged the customer and crashed before committing, the next attempt gets the _same_ charge back from the provider instead of creating a new one, and the order finally gets persisted.

### Approach B: Compensate via a Domain Event

Idempotency keys only help when you can replay with the same inputs.
Sometimes you can't - the user gave up, the request was cancelled, or the failure is permanent.

In that case, the money is real and needs to come back.
Make the failure itself a first-class event and refund out-of-band:

```csharp {12,15}
public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
{
    var order = Order.Create(request.CustomerId, request.Items);

    var charge = await payments.ChargeAsync(order.Id, order.Total, ct);
    if (charge.IsFailure) return charge;
    order.MarkPaid(charge.Value.TransactionId);

    try
    {
        orders.Insert(order);
        order.Raise(new OrderPlacedEvent(order.Id));
        await unitOfWork.SaveChangesAsync(ct);
    }
    catch (Exception ex)
    {
        await outbox.PublishAsync(
            new PaymentFailedEvent(
                order.Id,
                charge.Value.TransactionId,
                order.Total,
                Reason: ex.Message),
            ct);
        throw;
    }

    return Result.Success();
}
```

A background consumer subscribes to `PaymentFailedEvent` and issues the refund, using the transaction ID as its own idempotency key.
This turns a scary cross-process compensation into a normal, observable, retryable [**message handler**](idempotent-consumer-handling-duplicate-messages).

In practice, I use Approach A for transient failures and Approach B for permanent ones. They aren't mutually exclusive.

## When the Saga Pattern Wins Instead

The strategies above work when one use case coordinates a small number of side effects in a single service.
Once the work spans multiple services and needs to survive process restarts, you're in [**saga**](implementing-the-saga-pattern-with-masstransit) territory.

The rule I use: if you can fit the recovery logic in your head, a well-designed use case is enough. If you can't, reach for a saga.

## Summary

A use case is a unit of _intent_, not a unit of _atomicity_.

- **Transactional** work commits with the database, last.
- **Irreversible** work goes through the [**Outbox pattern**](implementing-the-outbox-pattern), not the use case.
- **External, reversible** work uses idempotency keys first, compensating events second.
- **Never** swallow failures to make the use case "look successful".

Most of the production bugs I've debugged in event-driven systems come down to a use case that lied about whether it succeeded.
Stop lying, and the system gets a lot easier to reason about.

If you want to see this kind of thinking applied across a full system, that's exactly what I build inside [**Modular Monolith Architecture**](/modular-monolith-architecture).

Thanks for reading.

And stay awesome!

---



<Sponsorships>

A live directory for your infrastructure that replaces hardcoded ownership logic in your alert rules -
that's Catalog by [**incident.io**](https://fandf.co/4cIIfB2).
Add a service, update Catalog, and your entire response system reconfigures itself.
[**Read the blog to learn more**](https://fandf.co/4cIIfB2).

[**Teleport**](https://fandf.co/3PhCocK) replaces static credentials with short-lived certificates bound to cryptographic identity.
One identity layer and workflow across servers, Kubernetes, databases, cloud, and MCP.
No vaults, no standing privileges, no secrets rotation.
[**See how it works →**](https://fandf.co/3PhCocK)

</Sponsorships>

I've written before about implementing [**API versioning**](api-versioning-in-aspnetcore) in ASP.NET Core.

But the more important question isn't _how_ to version an API.
It's _when_.

Every API team eventually reaches for the same escape hatch:

> Just create `v2`.

It sounds responsible.
Except now you maintain two APIs, two sets of docs, two behaviors, and a migration project clients will postpone for as long as possible.

I also touched on this briefly in [**my REST API design mistakes article**](the-5-most-common-rest-api-design-mistakes-and-how-to-avoid-them), but I want to make the point more directly today:

**Versioning is a compatibility tool. It is not a design strategy.**

Most API changes do not require a new version.
They require better change management.

And that distinction matters.

If you treat every contract change as a versioning problem, you end up cloning APIs.
If you treat it as a change management problem, you start asking better questions:

- Can I add instead of replace?
- Can old and new behavior coexist for a while?
- Can I introduce a new operation instead of mutating an old one?
- Can I deprecate this safely with telemetry and a migration path?

That mindset leads to APIs that age much better.

## What Actually Breaks Clients?

Breaking changes usually aren't about the URL alone.

Clients break when you:

- Remove or rename fields
- Change the meaning of existing data
- Tighten request validation
- Change pagination or error formats
- Assume enum-like values are closed forever

This breaks a client just as surely as deleting an endpoint:

```json
// Before
{ "total": 100 }

// After
{ "total": { "amount": 100, "currency": "USD" } }
```

You didn't change the path.
You didn't rename the endpoint.
You still broke clients.

So instead of asking, "Should this be v2?", ask, "Can the old and new contract safely coexist?"

I'll use a simple `orders` API as the running example for the rest of the article.

## The Compatibility Rules

When I want an API to age well, I keep four rules in mind:

- Keep existing fields and behavior in place
- Don't turn optional request data into required data
- Don't change what an existing operation does
- Make anything new additive and optional by default

These map directly onto the four rules from Z. Nemec's [API Change Management](https://medium.com/good-api/api-change-management-2fe5bba32e9b) article: don't take anything away, don't change processing rules, don't make optional things required, and anything you add must be optional.

If you follow those rules, many "versioning problems" turn back into ordinary contract evolution.

## 1. Add, Don't Replace

The safest change is usually an additive one.

Let's say your original `GET /orders/{id}` response looked like this:

```json
{
  "id": "ord_123",
  "status": "paid",
  "total": 100
}
```

Instead of replacing `total`, add a new field:

```json
{
  "id": "ord_123",
  "status": "paid",
  "total": 100,
  "totalMoney": {
    "amount": 100,
    "currency": "USD"
  }
}
```

Existing clients keep using `total`.
New clients can migrate to `totalMoney`.
You mark the old field as deprecated and remove it only after a real migration window.

The same idea applies beyond fields.
If you need richer semantics, don't mutate a field into a different shape.
Add a new field, a new link, or a new operation that carries the new meaning explicitly.

Sometimes an ugly contract is the price of compatibility.

## 2. Make Clients Tolerant Readers

A well-behaved client should not explode because the server added a field it doesn't understand.

If the response evolves from this:

```json
{
  "id": "ord_123",
  "status": "paid"
}
```

to this:

```json
{
  "id": "ord_123",
  "status": "paid",
  "estimatedDeliveryDate": "2026-05-29"
}
```

older clients should ignore the extra property and keep working.

In .NET, `System.Text.Json` helps because unknown properties are ignored by default.
The real risk is usually overly strict generated SDKs or contract tests that assert exact JSON equality.

This is one of the most common self-inflicted problems I see.
Teams say they want backward compatibility, then generate client models that reject any unexpected field in the response.

That is not a compatibility strategy.
That is a trap.

Your server should be free to add optional data.
Your clients should be resilient enough to ignore what they don't understand.

## 3. Don't Change What an Existing Operation Does

Fields and shapes get most of the attention in compatibility discussions, but the most dangerous breaking changes hide in **behavior**.

The URL is the same.
The request body is the same.
The response shape is the same.
What the operation _does_ on the server is different.

Take `DELETE /orders/{id}`.

When the API shipped, that endpoint was a soft delete.
The order moved into an `archived` state, stayed in the database, still showed up in audit reports, and could be restored by support.

The contract that clients built on wasn't just the HTTP verb and the path.
It was the full behavior:

- The order is recoverable
- Related invoices and shipments are untouched
- Audit history is preserved
- The same call is safe to retry

Months later, the team decides soft-delete is messy.
The "fix" turns `DELETE /orders/{id}` into a hard delete:

- The order row is gone
- Related invoices cascade or get orphaned
- Audit history loses references
- Retrying after a network blip can wipe the wrong record

No client noticed at code-review time.
The SDK call still compiles.
The response is still `204 No Content`.
A support tool that used to call `DELETE` and then "undo" it now silently destroys data.

This is exactly the kind of change Z. Nemec's rules call out:
**you must not change the processing rules of an existing operation.**
Once clients have integrated, the behavior _is_ the contract, even if it was never written down anywhere.

The same pattern shows up in subtler ways:

- `POST /orders` used to be idempotent on a client-supplied key, then quietly stops being
- `POST /orders/{id}/cancel` used to refund automatically, then stops issuing refunds because "refunds should be a separate call"
- `PUT /orders/{id}` used to be a full replace, then becomes a partial merge
- A webhook used to fire once per order, now fires per line item

Each of these keeps the URL, the verb, and the JSON shape stable.
Each one breaks every existing integration in a way that won't show up in a schema diff.

The safe move is the same as before: **add, don't mutate.**

If you want a hard delete, expose it as a new operation and leave the old one alone:

```http
DELETE /orders/{id}            # still soft-delete, unchanged
DELETE /orders/{id}?purge=true # new, opt-in hard delete
```

Or introduce a new resource entirely (`DELETE /orders/{id}/purge`) so the destructive behavior has its own name and its own permissions.

The rule is simple: **once an operation ships, its behavior is part of the contract.**
You can add new operations next to it.
You can deprecate it.
You cannot quietly change what it does.

## 4. Be Very Careful With Validation

This one is underrated.

There are two flavors of the same mistake:

- Taking an existing optional field and making it required
- Adding a brand-new field and making it required from day one

Both break older clients in exactly the same way.
The endpoint path doesn't move, but requests that used to succeed now get rejected.

Here's a simple example using `POST /orders`.

Yesterday this request was valid:

```json
{
  "customerId": "cus_123",
  "currency": "USD"
}
```

Today the API requires a country for tax calculation:

```json
{
  "customerId": "cus_123",
  "currency": "USD",
  "country": "US"
}
```

Whether `country` was previously optional or didn't exist at all, the result is the same: every existing integration starts failing at runtime.

A safer path is to accept missing values for older clients, infer defaults where possible, or introduce a new operation for the stricter workflow.

For example:

- Accept missing `country` during a transition window
- Infer it from an existing billing profile if you can
- Add a new `POST /checkout-sessions` flow that requires the richer request model

Response changes usually get careful design review.
Request validation changes deserve the same scrutiny.
And the underlying rule is the one that catches both flavors: **anything you add to the contract has to be optional, and anything that was optional has to stay optional.**

## A New Operation Is Often Cheaper Than a New Version

Sometimes the use case really did change enough that piling more flags and optional parameters onto an existing endpoint becomes confusing.

This is what a bad evolution path looks like:

```http
POST /orders?validateOnly=true&includeTaxEstimate=true&reserveInventory=true
```

At that point you don't have one clean operation.
You have multiple workflows hiding behind one endpoint.

That's when I prefer a new operation or resource over a whole API version.

```http
POST /orders
POST /orders/quote
POST /checkout-sessions
```

This keeps the old contract stable while giving the new behavior a clean home.

`POST /orders` stays the simple "place an order" endpoint.
`POST /orders/quote` becomes the "tell me what this would cost" operation.
`POST /checkout-sessions` can support a richer, more guided flow without contaminating the original contract.

That is usually much cheaper than creating `/v2/orders` and dragging the rest of your API along with it.

## Deprecate Like You Mean It

This is the missing half of API change management.

Most deprecations are fake.
They exist in docs, but nothing operational happens.

A real deprecation process should include four things:

1. Mark the old field or endpoint as deprecated in your OpenAPI description.
2. Signal the deprecation at runtime.
3. Give consumers a migration path.
4. Measure actual usage before removing anything.

If you're on HTTP, runtime signaling can be as simple as response headers like these:

```http
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrations/orders-total>; rel="deprecation"
```

Now the deprecation is visible in the docs, visible in live traffic, and connected to an actual migration guide.

And this is where telemetry matters.
If you don't know which clients still use the deprecated field or endpoint, you are not managing change.
You are guessing.

Track usage by client ID, API key, tenant, or application name.
Then wait until usage is effectively gone before removing anything.

## When Versioning Is Actually The Right Call

I am not anti-versioning.

Version when the old and new semantics cannot coexist safely.
Version when the resource model changed fundamentally.
Version when compatibility rules would force you into a contract nobody can reason about.

In those cases, version deliberately.

And deliberate versioning means choosing the smallest break you can justify.

Sometimes that's a new endpoint shape.
Sometimes it's a representation variant.
Sometimes, especially for public APIs, it's straightforward URL versioning because it is explicit and easy to communicate.

The key is not which mechanism you pick.
The key is that you reached for it because coexistence failed, not because it was the first idea on the table.

And if you do version, pair it with an actual deprecation process:

- Mark old fields or endpoints as deprecated
- Communicate a removal date
- Give clients migration examples
- Monitor usage before removing anything

The real work is not creating `v2`.
The real work is getting consumers off `v1`.

## Takeaway

The best API version is often the one you never have to create.

If you want a simple decision rule, use this:

1. Can I add instead of replace?
2. Can old and new contracts coexist during a migration window?
3. Can I introduce a new operation instead of mutating an old one?
4. Can I deprecate the old shape with docs, headers, and telemetry?

If the answer is yes, you probably don't need a new version.

If the answer is no, and the old and new worlds genuinely cannot live side by side, version deliberately.

That's the real point.

Design contracts to evolve.
Treat clients as long-lived integrations, not just today's code.
And reserve versioning for the cases where compatibility truly runs out.

If you want to go deeper on designing and evolving HTTP APIs, check out [**Pragmatic REST APIs**](/pragmatic-rest-apis).
It's where I cover the patterns, trade-offs, and implementation details I use when building APIs that need to survive real clients and real change.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

Are you using VS Code or Cursor for C#?
AI writes your C# code - [**ReSharper**](https://www.jetbrains.com/resharper/?product=vsc&utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper-vsc) makes sure it's actually correct.
[**Give it a try**](https://www.jetbrains.com/resharper/?product=vsc&utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper-vsc)!

[**Aiven's developer tier for Apache Kafka**](https://fandf.co/4cVcIdL) lets you ditch the local setup
and provision a managed cluster with an integrated Schema Registry and REST Proxy in under two minutes.
For $29/month, you get 100 partitions and 20 topics on the same stack used for enterprise-grade workloads,
providing a production-ready playground for prototyping your event-driven services.
[**Start building**](https://fandf.co/4cVcIdL).

</Sponsorships>

A lot of the "DDD-ish" .NET code I review scatters business rules across handlers, validators,
and controllers, and barely puts any on the domain model itself.

Each copy of the same rule drifts a little over time, and whether a given object is _valid_ starts to depend on which path the caller took to reach it.

You can absolutely build a working system this way.
I've shipped plenty of procedural code with enough `if`-checks to keep things in line.
But there's a cleaner way to think about it, and it starts with a single idea.

## What Is an Invariant?

An **invariant** is a rule about an object that must hold true for as long as the object exists.

Not just when you save it, or when a validator happens to run.
The rule has to hold every time you touch the object, no matter how it got into memory.

A few examples:

- A `Course` always has a non-empty title.
- An `Order` total always equals the sum of its line items.
- A `Subscription` is in exactly one state: `Trial`, `Active`, `PastDue`, or `Canceled`.
- A published course has at least one lesson.

None of these mention validation, persistence, or HTTP.
They're statements about the _domain_, and they should be true regardless of how the object got loaded.

## Where Procedural Code Goes Wrong

Take a simple `Course` written the way most CRUD-ish .NET apps still write it:

```csharp
public class Course
{
    public string Title { get; set; }
    public CourseStatus Status { get; set; }
    public DateTime? PublishedOn { get; set; }
    public decimal Price { get; set; }
}
```

There's no constructor and every property has a public setter, so the class is willing to accept any combination of values.

To keep the data correct, the rules end up scattered across the application:

- `CreateCourseValidator` checks the title isn't empty.
- `PublishCourseHandler` sets `Status` and `PublishedOn`, and remembers to check the course isn't already published.
- `ChangePriceHandler` checks the course isn't archived.
- A new endpoint shows up, someone copies an existing handler, and the archive check quietly goes missing.

Every rule lives in a place that just happens to be on the path the request took.
Nothing on the `Course` itself prevents it from drifting into an invalid state.

That's the real cost of an [**anemic model**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model).
It isn't that there's no behavior on the class.
It's that the class makes no promises, so every caller has to enforce the rules itself.

## Always-Valid: The Model as the Source of Truth

The shift I want to make is simple: the model never accepts an invalid state.

If you're holding a `Course` reference, you can trust it.
You don't need an `if (course.Title is null)` somewhere down the call stack, you don't need a parallel validator double-checking, and you don't need to hope the handler remembered the right guard.

Three moves get you there.

### 1. Block construction of invalid objects

A `Course` without a title shouldn't exist, so the easiest fix is to make it impossible to construct.

```csharp
public class Course
{
    private Course(CourseId id, string title, Money price)
    {
        Id = id;
        Title = title;
        Price = price;
        Status = CourseStatus.Draft;
    }

    public static Result<Course> Create(string title, Money price)
    {
        if (string.IsNullOrWhiteSpace(title))
        {
            return CourseErrors.TitleRequired;
        }

        return new Course(CourseId.New(), title, price);
    }
}
```

A private constructor with a static factory gives you a single, well-known place where a `Course` can come into existence, and that's where the validation runs.
From that point on, any code holding a `Course` reference can assume it has a valid title.

[**Value objects**](value-objects-in-dotnet-ddd-fundamentals) like `Money` apply the same idea at a smaller scope, so a `Money` can't be negative or be missing its currency by the time you're using it.

### 2. Encapsulate state transitions

Once construction is locked down, the next leak is state changes.
The class should control how it changes, instead of leaving that up to whoever has a reference to it.
No setters, and every change goes through a method that knows the rules.

```csharp
public Result Publish(IDateTimeProvider clock)
{
    if (Status != CourseStatus.Draft)
    {
        return CourseErrors.AlreadyPublished;
    }

    if (_lessons.Count == 0)
    {
        return CourseErrors.CannotPublishWithoutLessons;
    }

    Status = CourseStatus.Published;
    PublishedOn = clock.UtcNow;
    return Result.Success();
}
```

The handler doesn't need to know whether the course was already published, and it doesn't need to remember to check for empty lessons.
It calls `Publish` and propagates whatever result comes back.
The rule lives next to the state it protects, in one place.

### 3. Encapsulate the aggregate

Some rules span multiple entities inside the same boundary.
The aggregate root is the right place to enforce those, because it's the transactional boundary.

Take this rule: a published course must have at least one lesson, and lessons can't be removed once it's published.

The wrong way is to expose `Lessons` as a mutable collection and rely on the application service to remember the rule everywhere it's used.
The right way is to keep the collection private and force every change through the root:

```csharp
public sealed class Course
{
    private readonly List<Lesson> _lessons = [];
    public IReadOnlyCollection<Lesson> Lessons => _lessons.AsReadOnly();

    public Result RemoveLesson(LessonId id)
    {
        if (Status == CourseStatus.Published)
        {
            return CourseErrors.CannotModifyPublishedLessons;
        }

        var lesson = _lessons.FirstOrDefault(l => l.Id == id);
        if (lesson is null)
        {
            return CourseErrors.LessonNotFound;
        }

        _lessons.Remove(lesson);
        return Result.Success();
    }
}
```

When a rule needs to span _two_ aggregates instead of one, that's a different problem, and I'd reach for a [**domain event**](how-to-use-domain-events-to-build-loosely-coupled-systems) rather than letting one aggregate reach into another.

## What You Actually Get

You can write the same system procedurally, and it can work well.
The thing you give up is **trust**.

In a procedural system, every caller shares responsibility for not breaking the rules.
In an always-valid model, that responsibility lives on the domain model.
The difference compounds over time:

- Validators don't drift, because there's nothing to duplicate.
- Code reviews focus on behavior instead of "did we forget a check?".
- New endpoints can't accidentally bypass a rule that lives on the entity.
- Tests stop covering scenarios that aren't even expressible.

The model goes from being a passive data carrier to being the smallest, sharpest place where the business rules live.

Fundamentally, this is about **encapsulation**.
The model encapsulates the rules that govern its state, and the rest of the system interacts with it through a well-defined interface.
That leads to cleaner code, fewer bugs, and a more maintainable system overall.

## Summary

An invariant is a rule that must always hold true while the object exists, and the cleanest place to enforce it is on the object itself.

- **Construction invariants** belong in a private constructor behind a factory.
- **State transition invariants** belong in methods that own the state they change.
- **Aggregate-wide invariants** belong on the root, with child entities accessed only through it.

The tradeoff is that you give up the freedom to write procedural code that could be easier to understand in the short term,
but you get a model that you can trust to always be valid.

If you want to go deeper into modeling aggregates, value objects, and rich behavior across a real system,
I think you will enjoy [**Pragmatic Domain-Driven Design**](/pragmatic-domain-driven-design).

See you next week.

---



<Sponsorships>

AI-assisted development often falters when agents operate in a vacuum,
blind to the unspoken rules and architectural nuances unique to a specific codebase.
By grounding AI agents in repo-aware dynamic context, [**Sonar's Context Augmentation**](https://fandf.co/480ZOcJ)
reduces iterative rework with first-pass precision, ensuring every AI-generated line
respects the architectural and security standards of your project.
[**Check it out**](https://fandf.co/480ZOcJ).

[**exe.dev**](https://fandf.co/4cMnV0c) reimagines cloud dev with instant persistent VMs
\- SSH in, build anything, deploy without touching infrastructure.
[**Learn more here**](https://fandf.co/4cMnV0c).

</Sponsorships>

I'll be honest. For years, my projects didn't look like the **test pyramid**.

A wide base of unit tests, a narrow middle of integration tests, a tiny sliver of end-to-end tests at the top.
I'd nod along in conference talks, then go back to my own code and do something different.

A thin layer of unit tests for the things worth unit-testing.
A thick slab of integration tests against real PostgreSQL, real RabbitMQ, real HTTP.
A handful of end-to-end tests for the flows that would get me fired if they broke.

And I shipped with more confidence that way, not less.
Here's why, and here's the shape I actually use.

## Where the Pyramid Comes From

The pyramid was popularized by Mike Cohn in 2009, when integration tests meant a shared database server, flaky CI, and 20-minute builds.
Unit tests with mocks were the pragmatic compromise.

<Image
  src="/blogs/mnw_191/test_pyramid.png"
  width={2519}
  height={1153}
  alt="The classic test pyramid, with a wide base of unit tests, a narrow middle of integration tests, and a tiny sliver of end-to-end tests at the top."
/>

That world is gone.
With [**Testcontainers**](testcontainers-integration-testing-using-docker-in-dotnet), I can spin up PostgreSQL, Redis, and RabbitMQ in a fresh container per test class in a few seconds.
The [**Aspire test host**](https://learn.microsoft.com/en-us/dotnet/aspire/testing/overview) takes this further by wiring up your entire application graph.
The argument that real dependencies are too expensive mostly doesn't apply anymore.

But the advice didn't update.

## The Bug That Convinced Me

A few years ago I had a service with **94% unit test coverage**. All green.

A user reported that deleting an account didn't actually delete their data.
The bug was three lines long:

```csharp
public async Task Handle(DeleteAccountCommand command, CancellationToken ct)
{
    var account = await _repository.GetByIdAsync(command.AccountId, ct);
    account.MarkAsDeleted();
    // Missing: await _unitOfWork.SaveChangesAsync(ct);
}
```

The honest diagnosis is that the test for this case was never written.
You can absolutely verify `SaveChangesAsync` was called with a mock.
But in a codebase where that test is _one of hundreds_ of handler tests, each with its own mock setup and its own verification list, it's the kind of assertion people forget.
I forgot.

A single integration test against a real database would have caught it without anyone having to remember.
That's the point: the fewer invariants your test style forces you to remember, the fewer bugs slip through.

That was the last week I took the test pyramid seriously.

## What Unit Tests Are Actually Good At

I still write unit tests. Just not many.

They earn their keep when the logic is non-trivial, pure (no I/O, no time, no randomness), and hard to exercise end-to-end.
That's a specific set of code: [**value objects**](value-objects-in-dotnet-ddd-fundamentals) and [**rich domain models**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model), pricing and tax calculations, parsers, mappers, serializers.

Notice what's **not** on that list: application services, handlers, controllers, repositories, infrastructure.
Those live at the seams, and the seams are where real bugs live.

## What I Actually Write Instead

Here's the shape I've settled on for a typical .NET service or [**modular monolith**](what-is-a-modular-monolith).

### Layer 1: A thin base of unit tests

Maybe 15-25% of the test count. All domain logic.
No mocks of collaborators. If a unit test needs a mock, I usually pull the test up to the integration layer instead.

```csharp
[Fact]
public void Confirm_WhenPending_TransitionsToConfirmed()
{
    var order = Order.Create(CustomerId.New(), Money.Usd(100));

    order.Confirm();

    order.Status.Should().Be(OrderStatus.Confirmed);
    order.DomainEvents.Should().ContainSingle(e => e is OrderConfirmedEvent);
}
```

No container or mocks.
Microseconds per test.
This is what unit tests are for.

### Layer 2: A thick middle of integration tests

The majority. Maybe 60-70% of the suite.
Every [**command and query handler**](cqrs-pattern-with-mediatr), every HTTP endpoint, every message consumer gets a test that runs against **real infrastructure** inside Testcontainers.
In a [**modular monolith**](testing-modular-monoliths-system-integration-testing), this is where you verify that modules talk to each other correctly across their public APIs.

```csharp
public class DeleteAccountTests(IntegrationTestWebAppFactory factory)
    : BaseIntegrationTest(factory)
{
    [Fact]
    public async Task DeleteAccount_WhenAccountExists_MarksAccountAsDeleted()
    {
        var account = await CreateAccountAsync();

        var response = await HttpClient.DeleteAsync($"/accounts/{account.Id}");

        response.StatusCode.Should().Be(HttpStatusCode.NoContent);

        var stored = await DbContext.Accounts
            .IgnoreQueryFilters()
            .SingleAsync(a => a.Id == account.Id);

        stored.IsDeleted.Should().BeTrue();
    }
}
```

That test exercises the HTTP layer, routing, model binding, authorization, the handler, the unit of work, EF Core, and PostgreSQL.
It proves the thing you actually care about: **when I call this endpoint, the row changes.**
And it does it without anyone having to remember to assert `SaveChangesAsync` was called.

### Layer 3: A small cap of end-to-end tests

Under 10%. Only the flows where a silent failure would be a commercial or compliance problem.
Signup, payment, refund, password reset, [**two-factor enrollment**](how-to-implement-two-factor-authentication-in-aspnetcore).
They're slow and occasionally flaky, but they catch the one failure mode everything else misses: _the system as a whole still works_.

### Layer 0: Architecture and contract tests

Often forgotten, but they're part of the suite.
[**Architecture tests**](5-architecture-tests-you-should-add-to-your-dotnet-projects) enforce layering and module boundaries.
Contract tests verify that message schemas and API shapes don't drift.
They run in milliseconds and catch the "six months from now, someone will break this without realizing" kind of bug.

The shape that comes out of this is closer to Kent C. Dodds' **testing trophy** than a pyramid.
The fat middle is deliberate. That's where my confidence comes from.

## The Usual Objections

**"Integration tests are slow."**
My typical integration suite runs in 2-4 minutes in CI with Testcontainers reuse and test-class parallelization.
Slower than unit tests, yes. Faster than finding the bug in production.

**"Mocks are fine if you're disciplined."**
Maybe. But every large codebase I've audited that leaned heavily on mocks had the same pathology: tests that pass after a refactor even though the refactor broke production.
That's not discipline failing. That's the tool being pointed in the wrong direction.

## Summary

The test pyramid was good advice for 2009 infrastructure and poor advice for 2026 infrastructure.
Testcontainers and Aspire changed the economics, and the fastest feedback loop that still tells you the truth is now an integration test against real dependencies.
Unit tests still belong on pure domain logic. Everything at the seams belongs in the integration layer.

If you want to see how I wire this into a real system, with the [**integration test harness**](testing-modular-monoliths-system-integration-testing), module boundaries, and the full [**Clean Architecture**](/pragmatic-clean-architecture) setup, check out [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).
It's the same approach I use on my own projects.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**AI Infrastructure**](https://fandf.co/4mAyU1q) That Lets Developers Build, Deploy, and Scale Without Friction.
Runpod removes cloud complexity so you can focus on shipping AI.
[**Start building with Runpod**](https://fandf.co/4mAyU1q).

JetBrains is conducting a survey to [**better understand how .NET dev tools impact developer productivity**](https://surveys.jetbrains.com/s3/NET-Tools-DX-Survey-NL18?utm_source=newsletter_newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=survey),
and your perspective could really help the company make its tooling even better.
[**Take the survey**](https://surveys.jetbrains.com/s3/NET-Tools-DX-Survey-NL18?utm_source=newsletter_newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=survey)
and get a chance to win a small prize.

</Sponsorships>

I'll be honest. I resisted primary constructors for a while.

When C# 12 extended them from `record` types to regular classes and structs, my first reaction was skepticism.
An implicit mutable capture instead of explicit `readonly` fields?
That felt like trading safety for convenience.

But after using them across several projects, I changed my mind.
The boilerplate they eliminate in DI service classes is significant, and the pitfall I was worried about is manageable once you know about it.

Here's what convinced me to switch, and the one thing you need to watch out for.

## What Changed My Mind

Here's what my service classes used to look like:

```csharp
public class OrderService
{
    private readonly IOrderRepository _orderRepository;
    private readonly ILogger<OrderService> _logger;

    public OrderService(
        IOrderRepository orderRepository,
        ILogger<OrderService> logger)
    {
        _orderRepository = orderRepository;
        _logger = logger;
    }

    public async Task<Order?> GetOrderAsync(Guid id)
    {
        _logger.LogInformation("Fetching order {OrderId}", id);

        return await _orderRepository.GetByIdAsync(id);
    }
}
```

And here's what they look like now:

```csharp
public class OrderService(
    IOrderRepository orderRepository,
    ILogger<OrderService> logger)
{
    public async Task<Order?> GetOrderAsync(Guid id)
    {
        logger.LogInformation("Fetching order {OrderId}", id);

        return await orderRepository.GetByIdAsync(id);
    }
}
```

The field declarations, the constructor body, the assignments. All gone.
The parameters are captured and available throughout the class body.

This is the most common use case for primary constructors: [**dependency injection**](improving-aspnetcore-dependency-injection-with-scrutor) in service classes.
You declare what you need, and use it directly.

## Where I Use Them Most: DI Service Classes

The place where primary constructors sold me is ASP.NET Core service classes.
This is where I spend most of my time, and the boilerplate savings add up fast.

Here's a more realistic example from a checkout flow:

```csharp
public class CheckoutService(
    IPaymentProcessor paymentProcessor,
    IOrderRepository orderRepository,
    ILogger<CheckoutService> logger,
    IOptions<CheckoutOptions> options)
{
    public async Task<CheckoutResult> ProcessAsync(
        Cart cart,
        CancellationToken ct = default)
    {
        var settings = options.Value;

        if (cart.Total < settings.MinimumOrderAmount)
        {
            logger.LogWarning("Order below minimum: {Total}", cart.Total);
            return CheckoutResult.BelowMinimum;
        }

        var order = Order.Create(cart);

        await paymentProcessor.ChargeAsync(order, ct);
        await orderRepository.SaveAsync(order, ct);

        logger.LogInformation("Checkout complete for order {OrderId}", order.Id);

        return CheckoutResult.Success;
    }
}
```

Four dependencies, zero boilerplate.
The class reads top-to-bottom without any noise.

This pattern works well because service classes typically don't need to validate or transform their dependencies.
The DI container provides them, and you use them.
Primary constructors are a perfect fit for this.

## Entity Construction (With a Caveat)

I also started using primary constructors for [**domain entities**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model) and [**value objects**](value-objects-in-dotnet-ddd-fundamentals) where you want to enforce required parameters at construction time:

```csharp
public class Order(Guid customerId, Money total)
{
    public Guid Id { get; } = Guid.NewGuid();
    public Guid CustomerId { get; } = customerId;
    public Money Total { get; } = total;
    public OrderStatus Status { get; private set; } = OrderStatus.Pending;
    public DateTime CreatedAt { get; } = DateTime.UtcNow;

    public void Confirm()
    {
        if (Status != OrderStatus.Pending)
        {
            throw new InvalidOperationException(
                $"Cannot confirm order in {Status} status.");
        }

        Status = OrderStatus.Confirmed;
    }
}
```

There's no way to create an `Order` without a `customerId` and `total`.
The primary constructor makes this constraint visible at the type declaration level.

Notice the key difference from the service class pattern: here, I'm assigning primary constructor parameters to **properties with initializers** (`= customerId`).
This is important, and it leads to the biggest pitfall.

## The Pitfall That Almost Stopped Me

This was the reason I held off for so long.

**Primary constructor parameters are not `readonly` fields.**

When you use a primary constructor parameter directly in the class body (like we did in the service class), the compiler captures it as a **mutable variable**.
There's no `readonly` backing field generated behind the scenes.

This means you can accidentally reassign a parameter:

```csharp
public class OrderService(
    IOrderRepository orderRepository,
    ILogger<OrderService> logger)
{
    public async Task<Order?> GetOrderAsync(Guid id)
    {
        logger.LogInformation("Fetching order {OrderId}", id);

        return await orderRepository.GetByIdAsync(id);
    }

    public void SomeOtherMethod()
    {
        // This compiles. No warning. No error.
        orderRepository = null!;
        logger = null!;
    }
}
```

This compiles without any warning.

With a traditional constructor and `private readonly` fields, the compiler would stop you immediately.
With primary constructors, it stays silent.

**If you need immutability guarantees**, explicitly assign the parameter to a `readonly` field:

```csharp
public class OrderService(
    IOrderRepository orderRepository,
    ILogger<OrderService> logger)
{
    private readonly IOrderRepository _orderRepository = orderRepository;
    private readonly ILogger<OrderService> _logger = logger;

    public async Task<Order?> GetOrderAsync(Guid id)
    {
        _logger.LogInformation("Fetching order {OrderId}", id);

        return await _orderRepository.GetByIdAsync(id);
    }
}
```

But now you've lost most of the benefit of primary constructors.
You're back to field declarations and assignments, just with a different syntax.

In practice, I've never actually hit this bug in a DI service class.
You're unlikely to accidentally reassign `logger` in the middle of a method.
But it **can** bite you in entity classes or value types where immutability actually matters.
That's the one place where I still stay cautious.

## Where I Still Use Traditional Constructors

I haven't switched everything over.
Here are the cases where I stick with the traditional approach:

**Complex validation logic.** If you need to validate parameters before assigning them, you need a constructor body:

```csharp
public class EmailAddress
{
    private readonly string _value;

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains('@'))
        {
            throw new ArgumentException(
                "Invalid email address.", nameof(value));
        }

        _value = value;
    }
}
```

Primary constructors don't give you a place to put validation logic before the class body runs.

**Multiple constructor overloads.** Primary constructors support one constructor signature.
If you need overloads, you'll have to chain secondary constructors with `this(...)`, which gets messy fast.

**Too many parameters.** Once you hit 5+ dependencies, the primary constructor line becomes hard to read.
At that point, your class probably has too many responsibilities, and [**refactoring**](5-awesome-csharp-refactoring-tips) it is a better solution than formatting tricks.

## Summary

Here's what I've settled on after using primary constructors across several projects:

- I use **primary constructors** for all my **DI service classes**. The boilerplate savings are worth it.
- They're useful for **entity construction** when you want to enforce required parameters at the type level.
- Primary constructor parameters are **captured as mutable variables**, not `readonly` fields. This is the one thing you need to know.
- I'm not afraid of the mutable capture pitfall in service classes, because it's unlikely to cause real bugs in that context.
- I stick with **traditional constructors** for validation-heavy types, multiple overloads, or classes with too many dependencies

The switch was worth it.
My service classes are shorter, easier to scan, and the pitfall is manageable with the right tooling.

That's all for today.
See you next week.

---



<Sponsorships>

AI workloads are unpredictable, which makes cloud commitments feel like a gamble.
[**Archera**](https://fandf.co/3PTpW3b) insures your commitments against underutilization,
so you can push coverage higher without the risk of getting stuck.
If usage drops, Archera covers the downside. Commitment Release Guarantee included.
[**Save with Archera**](https://fandf.co/3PTpW3b).

If you care about clean and maintainable .NET code, [**Pragmatic .NET Code Rules**](https://thecodeman.net/pragmatic-dotnet-code-rules)
is worth a look.
It's in presale and almost ready, with a focus on real-world practices.
[**Learn more**](https://thecodeman.net/pragmatic-dotnet-code-rules).

</Sponsorships>

Long-running business processes don't fit neatly into a single request.

Think about user onboarding: you register the user, send a verification email, wait for them to verify, and then send a welcome email.
Each step depends on the previous one.
If the user never verifies, you need a way to handle that.

The [**Saga pattern**](implementing-the-saga-pattern-with-masstransit) breaks this into a sequence of steps, each with its own message and handler.
If a step fails or times out, the saga runs [compensation logic](https://en.wikipedia.org/wiki/Compensating_transaction) instead of leaving the system in a broken state.

I've covered sagas with [**MassTransit**](implementing-the-saga-pattern-with-masstransit) and [**Rebus**](implementing-the-saga-pattern-with-rebus-and-rabbitmq) before.
Both work well, but their [state machine](https://en.wikipedia.org/wiki/Finite-state_machine) DSLs come with a fair amount of ceremony.
Since [MassTransit moved to a commercial license](mediatr-and-masstransit-going-commercial-what-this-means-for-you), more teams have been exploring Wolverine as an alternative.

[**Wolverine**](https://wolverinefx.net/) takes a [different approach](https://wolverinefx.net/guide/durability/sagas) - you write a class that extends `Saga`, define `Handle` methods for each message type, and [cascade new messages](https://wolverinefx.net/guide/handlers/cascading) from return values.
Wolverine handles routing, persistence, and correlation automatically.

## Configuring Wolverine

We need [**RabbitMQ**](event-driven-architecture-in-dotnet-with-rabbitmq) for message transport and [PostgreSQL](https://www.postgresql.org/) for durable saga state and messaging.

```csharp
var connectionString = builder.Configuration.GetConnectionString("user-mgmt");

builder.Host.UseWolverine(options =>
{
    options.UseRabbitMqUsingNamedConnection("rmq")
        .AutoProvision()
        .UseConventionalRouting();

    options.Policies.DisableConventionalLocalRouting();

    options.PersistMessagesWithPostgresql(connectionString!);
});
```

- `AutoProvision` creates RabbitMQ exchanges and queues automatically
- `UseConventionalRouting` routes messages to queues based on message type names
- `DisableConventionalLocalRouting` forces all messages through RabbitMQ instead of in-process handling
- [`PersistMessagesWithPostgresql`](https://wolverinefx.net/guide/durability/postgresql) stores saga state and messages in PostgreSQL. Wolverine uses [**lightweight saga storage**](https://wolverinefx.net/guide/durability/sagas#lightweight-saga-storage) to create a table per saga type, and the [**durable messaging**](https://wolverinefx.net/guide/durability/) infrastructure ensures nothing is lost if the process crashes

Wolverine gives you **three ways to persist saga state**.
[**Lightweight storage**](https://wolverinefx.net/guide/durability/sagas#lightweight-saga-storage) (what we're using) serializes saga state as JSON in a per-saga table with zero ORM config.
[**Marten**](https://wolverinefx.net/guide/durability/marten/sagas) stores sagas as [Marten](https://martendb.io/) documents with [optimistic concurrency](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) and strong-typed IDs.
[**EF Core**](https://wolverinefx.net/guide/durability/efcore/sagas) maps sagas into a flat, queryable table and lets you commit saga state with other data in a single transaction.
If you just need saga state management, lightweight storage is the simplest path.

Required packages:

```xml
<PackageReference Include="WolverineFx" Version="5.16.2" />
<PackageReference Include="WolverineFx.Postgresql" Version="5.16.2" />
<PackageReference Include="WolverineFx.RabbitMQ" Version="5.16.2" />
```

## The Saga Messages

Before building the saga, let's define all the messages it will work with:

```csharp
public record SendVerificationEmail(Guid UserId, string Email);
public record VerificationEmailSent(Guid Id);

public record VerifyUserEmail(Guid Id);

public record SendWelcomeEmail(Guid UserId, string Email, string FirstName);
public record WelcomeEmailSent(Guid Id);

public record OnboardingTimedOut(Guid Id) : TimeoutMessage(5.Minutes());
```

`OnboardingTimedOut` extends Wolverine's [`TimeoutMessage`](https://wolverinefx.net/guide/durability/sagas#timeout-messages), which automatically schedules a delayed delivery.
When the saga starts, Wolverine will deliver this message after 5 minutes.
If the user hasn't verified by then, the saga compensates.

## The Saga State Diagram

Here's how the saga transitions between states:

<div className="centered">
  <Image
    src="/blogs/mnw_189/saga_pattern_state_diagram.png"
    width={966 * 0.5}
    height={1160 * 0.5}
    alt="Saga pattern state diagram showing message flow from broker to consumer to database and processor."
  />
</div>

## Building the Saga

Here's the complete saga class:

```csharp
public class UserOnboardingSaga : Saga
{
    public Guid Id { get; set; }
    public string Email { get; set; } = string.Empty;
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
    public bool IsVerificationEmailSent { get; set; }
    public bool IsEmailVerified { get; set; }
    public bool IsWelcomeEmailSent { get; set; }
    public DateTime StartedAt { get; set; }

    // Step 1: Start the saga when UserRegistered is published
    public static (
        UserOnboardingSaga,
        SendVerificationEmail,
        OnboardingTimedOut) Start(
            UserRegistered @event,
            ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation(
            "Starting onboarding for user {UserId}", @event.Id);

        var saga = new UserOnboardingSaga
        {
            Id = @event.Id,
            Email = @event.Email,
            FirstName = @event.FirstName,
            LastName = @event.LastName,
        };

        return (
            saga,
            new SendVerificationEmail(saga.Id, saga.Email),
            new OnboardingTimedOut(saga.Id));
    }

    // Step 2: Verification email was sent
    public void Handle(
        VerificationEmailSent @event,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation(
            "Verification email sent for user {UserId}", Id);

        IsVerificationEmailSent = true;
    }

    // Step 3: User verified their email
    public SendWelcomeEmail Handle(
        VerifyUserEmail command,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation("Email verified for user {UserId}", Id);

        IsEmailVerified = true;

        return new SendWelcomeEmail(Id, Email, FirstName);
    }

    // Step 4: Welcome email sent - onboarding complete
    public void Handle(
        WelcomeEmailSent @event,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation("Onboarding complete for user {UserId}", Id);

        IsWelcomeEmailSent = true;

        MarkCompleted();
    }

    // Compensation: timeout handler
    public void Handle(
        OnboardingTimedOut timeout,
        ILogger<UserOnboardingSaga> logger)
    {
        if (IsEmailVerified)
        {
            logger.LogInformation(
                "Timeout ignored - email already verified for user {UserId}",
                Id);
            return;
        }

        logger.LogWarning(
            "Onboarding timed out for user {UserId} - email not verified",
            Id);

        MarkCompleted();
    }

    // NotFound: messages arriving for completed/deleted sagas
    public static void NotFound(
        VerifyUserEmail command,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogWarning(
            "Verify email received but saga {Id} no longer exists",
            command.Id);
    }

    public static void NotFound(
        OnboardingTimedOut timeout,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation(
            "Timeout received for already-completed saga {Id}",
            timeout.Id);
    }
}
```

A few things worth calling out.

**Starting the saga.** `Start` is a static factory that returns a tuple: the saga instance, a `SendVerificationEmail` command, and a [scheduled](https://wolverinefx.net/guide/messaging/message-bus#scheduling-message-delivery-or-execution) `OnboardingTimedOut` message. Wolverine persists the saga and delivers the messages for you.

**Handling messages.** Wolverine [**correlates messages**](https://wolverinefx.net/guide/durability/sagas#saga-message-identity) to the correct saga instance by looking for a `[SagaIdentity]` attribute, then `{SagaTypeName}Id`, then `Id`. Return `void` to update state silently, or return a message to cascade a new command.

> **Warning:** Do not call `IMessageBus.InvokeAsync()` within a saga handler to execute a command on that same saga. You'll be acting on stale or missing data. Use cascading messages (return values) for subsequent work.

**Completing the saga.** `MarkCompleted()` tells Wolverine to delete the saga state from PostgreSQL.

**Concurrency.** Wolverine applies [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) to saga state by default. If two messages for the same saga arrive at the same time, one succeeds and the other retries automatically.

**Timeout and compensation.** `OnboardingTimedOut` fires 5 minutes after the saga started. If the user verified, we ignore it. Otherwise, we compensate and end the saga. This is the key advantage over fire-and-forget workflows.

**NotFound handlers.** Static [`NotFound` methods](https://wolverinefx.net/guide/durability/sagas#when-sagas-are-not-found) handle messages for sagas that no longer exist. You **must** have one for any message type that could arrive after the saga is deleted. The timeout `NotFound` handler matters most: in the happy path, the saga completes before the timeout fires.

## The Sequence Flow

Here's the happy path where the user verifies before the timeout:

<Image
  src="/blogs/mnw_189/saga_pattern_sequence_diagram.png"
  width={2243}
  height={1930}
  alt="Saga pattern sequence diagram showing message flow from broker to consumer to database and processor."
/>

If the user never verifies, the `VerifyUserEmail` message never arrives.
After 5 minutes, `OnboardingTimedOut` fires and the saga compensates.

## Summary

Wolverine's `Saga` base class gives you a convention-driven way to implement long-running workflows:

- **`Start` methods** create and initialize the saga from a triggering event
- **`Handle` methods** process messages and cascade new commands via return values
- **`TimeoutMessage`** schedules delayed compensation without external schedulers
- **`MarkCompleted()`** cleans up the saga state when the workflow is done
- **`NotFound` handlers** gracefully handle messages for sagas that no longer exist

The Saga pattern shines when you have multi-step processes with potential failures.
Instead of hoping everything goes right, you design for the cases where it doesn't.

What I really like about Wolverine's approach is how little code you need.
You skip the state machine DSL and explicit correlation config entirely.

If you want to go deeper on orchestrating distributed workflows and building real-world sagas,
check out [**Modular Monolith Architecture**](/modular-monolith-architecture).

Hope this was useful. See you next week.

---


Previous issues of The .NET Weekly