
<Sponsorships>

Your GitHub Actions job says "waiting for a runner" but the runner is online and idle.
[**Depot**](https://fandf.co/4oWBY7F) breaks down why error messages mislead you and how workflow permissions, authentication,
and security contexts cause failures that look like infrastructure problems.
[**See what's really breaking your builds**](https://fandf.co/4oWBY7F).

[**Rider 2025.3**](https://blog.jetbrains.com/dotnet/2025/11/11/rider-2025-3-day-one-support-for-dotnet-10//?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dec)
is now available with day-one support for .NET 10, C# 14, and a completely new default UI.
Experience faster startup times and the latest coding features in your favorite cross-platform IDE.
[**Learn more here**](https://blog.jetbrains.com/dotnet/2025/11/11/rider-2025-3-day-one-support-for-dotnet-10//?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dec).

</Sponsorships>

**Solution files** have always been _that one file_ nobody wants to touch during a **merge conflict**.
I still remember the pain of resolving conflicts in large monorepo solutions with hundreds of projects.
Can I just say this was not fun?

Microsoft is (finally!) [addressing that](https://devblogs.microsoft.com/visualstudio/new-simpler-solution-file-format/) with **`.slnx`**: an **XML-based**, simpler solution format designed to be easier to read, edit, and merge.

Here is your practical guide to the future of .NET solutions.

## The problem with `.sln`

Classic `.sln` files are verbose: GUID-heavy project entries + configuration blocks that explode as your solution grows.
It's also a frequent source of merge conflicts.

To appreciate the new format, we must look at the old one.

Here's a typical `.sln` file from a moderately sized .NET solution:

```txt
Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.7.34031.279
MinimumVisualStudioVersion = 10.0.40219.1
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8FC526EA-218B-4615-8410-4E1850611F38}"
	ProjectSection(SolutionItems) = preProject
		.editorconfig = .editorconfig
		Directory.Build.props = Directory.Build.props
		Directory.Packages.props = Directory.Packages.props
	EndProjectSection
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{64A28C1B-09AF-426E-8721-D002BE554B48}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SharedKernel", "src\SharedKernel\SharedKernel.csproj", "{166778A2-518F-47F0-BBC7-DB49C76A963C}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Domain", "src\Domain\Domain.csproj", "{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Application", "src\Application\Application.csproj", "{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Infrastructure", "src\Infrastructure\Infrastructure.csproj", "{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Web.Api", "src\Web.Api\Web.Api.csproj", "{86506D03-3746-41E7-A645-97D3633981DB}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{1EB88D85-BE1E-46DE-99A2-2F02363060AF}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ArchitectureTests", "tests\ArchitectureTests\ArchitectureTests.csproj", "{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}"
EndProject
Project("{E53339B2-1760-4266-BCC7-CA923CBCF16C}") = "docker-compose", "docker-compose.dcproj", "{34BB3069-D5D0-4046-ACAD-A2025ED7678F}"
EndProject
Global
	GlobalSection(SolutionConfigurationPlatforms) = preSolution
		Debug|Any CPU = Debug|Any CPU
		Release|Any CPU = Release|Any CPU
	EndGlobalSection
	GlobalSection(ProjectConfigurationPlatforms) = postSolution
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Release|Any CPU.Build.0 = Release|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Release|Any CPU.Build.0 = Release|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Release|Any CPU.Build.0 = Release|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Release|Any CPU.Build.0 = Release|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Release|Any CPU.Build.0 = Release|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Release|Any CPU.Build.0 = Release|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Release|Any CPU.Build.0 = Release|Any CPU
	EndGlobalSection
	GlobalSection(SolutionProperties) = preSolution
		HideSolutionNode = FALSE
	EndGlobalSection
	GlobalSection(NestedProjects) = preSolution
		{166778A2-518F-47F0-BBC7-DB49C76A963C} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{86506D03-3746-41E7-A645-97D3633981DB} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA} = {1EB88D85-BE1E-46DE-99A2-2F02363060AF}
	EndGlobalSection
	GlobalSection(ExtensibilityGlobals) = postSolution
		SolutionGuid = {B948A3CC-9872-4612-ABD2-BB3D49671542}
	EndGlobalSection
EndGlobal
```

Good luck trying to make sense of that during a merge conflict!

## What `.slnx` looks like

A minimal `.slnx` is basically a list of projects in XML.

Here's the same solution as above, but in `.slnx` format.
We even have solution items, folders, and a docker-compose project.

```xml
<Solution>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/Application/Application.csproj" />
    <Project Path="src/Domain/Domain.csproj" />
    <Project Path="src/Infrastructure/Infrastructure.csproj" />
    <Project Path="src/SharedKernel/SharedKernel.csproj" />
    <Project Path="src/Web.Api/Web.Api.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/ArchitectureTests/ArchitectureTests.csproj" />
  </Folder>
  <Project Path="docker-compose.dcproj">
    <Build />
  </Project>
</Solution>

```

It looks remarkably similar to a `.csproj` file.

## How to Migrate Today

The `.slnx` format is available in recent versions of Visual Studio 2022 (v17.13+) and the .NET 9 SDK. Here is how you can switch.

**Option 1: The Command Line**

If you have the .NET 9 SDK installed (specifically 9.0.200 or later), you can migrate instantly via the CLI.

1. Open your terminal in the solution folder.
2. Run the migration command:

   ```bash
   dotnet sln migrate
   ```

3. This creates a new `.slnx` file alongside your old `.sln`.

At this point I would recommend deleting the old `.sln` file to avoid confusion.
There's no point in keeping both in the same repo.

**Option 2: Visual Studio "Save As"**

If you prefer the GUI, you can do this directly inside Visual Studio 2022 (or 2026).

1. Select the Solution in the Solution Explorer.
2. Go to `File` > `Save Solution As...`.

   <Image
     src="blogs/mnw_172/visual_studio_save_as.png"
     width={362}
     height={514}
     alt="The file menu in Visual Studio with the Save As option highlighted."
   />

3. Change the "Save as type" dropdown to Xml Solution File (\*.slnx).

   <Image
     src="blogs/mnw_172/save_as_xml_solution_file.png"
     width={317}
     height={130}
     alt="The Save As dialog in Visual Studio with the Xml Solution File option selected."
   />

## Why You Should Care

- **Fewer Merge Conflicts**: The #1 benefit.
  Because the file is simple XML without random GUIDs changing, git merges become trivial.
- **Human Readable**: You can open this in Notepad, understand it, and edit it without breaking your entire build.
- **Consistency**: It finally aligns the solution format with the project format (`.csproj`), which moved to simplified XML years ago.
- **Performance**: Smaller file sizes and simpler parsing mean slightly faster load times for massive solutions.

## Is it Ready?

As of late 2025/early 2026, `.slnx` is technically a **Preview** feature.

**Safe to use**?
Yes, the format is stable.

**Tooling support**?
Visual Studio 2022, Visual Studio 2026 and Rider support it well.
So does the .NET CLI.
Some older CI/CD pipelines or 3rd party tools might not recognize the extension yet.

**My recommendation**: Try it on a side project or a branch first.
If your CI pipeline passes, you are ready to modernize.

**I'm using this format** in all my new projects and have migrated several existing ones without issues.

---



<Sponsorships>

AI is changing observability, but dashboards aren't dead.
[**Honeycomb**](https://fandf.co/3Y52OPP) explains why human context still wins and where AI adds real value.
[**See why your dashboard isn't going anywhere... yet**](https://fandf.co/3Y52OPP).

[**Build AI Apps with MongoDB**](https://fandf.co/3KCqurL)\
Looking to stay ahead of the curve on AI?
[**MongoDB AI Learning Hub**](https://fandf.co/3KCqurL) has the technical training pathways and tools you need to uplevel your AI app-building game.
Explore practical guides, tutorials, and quick starts for all skills levels,
from foundational concepts like understanding AI tool stacks to advanced implementations using RAG, Atlas Vector Search, and LLM optimization.

</Sponsorships>

We have all built _that_ endpoint.

You know the one: the "Executive Dashboard" or the "User Summary" screen.
It's the endpoint that needs to fetch three or four completely unrelated sets of data to paint a complete picture for the user.
It needs the last 50 orders, the current system health logs, the user's profile settings, and maybe a notification count.

So, you write the code the standard way:

```csharp
var orders = await GetRecentOrdersAsync(userId);
var logs = await GetSystemLogsAsync();
var stats = await GetUserStatsAsync(userId);

return new DashboardDto(orders, logs, stats);
```

This works.
It's clean.
It's readable.
But there is a problem.

If `GetRecentOrdersAsync` takes 300ms, `GetSystemLogsAsync` takes 400ms, and `GetUserStatsAsync` takes 300ms,
your users are staring at a loading spinner for 1 full second (300 + 400 + 300).

In a distributed system, latency kills user experience.
Since these data sets are unrelated, we should be able to run them in parallel.
If we did, the total time would only be the duration of the slowest query (400ms).
That is a 60% performance improvement just by changing how we execute the code.

But if you try the naive approach with Entity Framework Core, your application will crash.

## The False Promise of Task.WhenAll

The most common mistake developers make when trying to optimize this is wrapping their existing repository calls in tasks and waiting for them all at once.

It looks something like this:

```csharp
// ❌ DO NOT DO THIS
public async Task<DashboardData> GetDashboardData(int userId)
{
    // These methods all use the same injected _dbContext
    var ordersTask = _repository.GetOrdersAsync(userId);
    var logsTask = _repository.GetLogsAsync();
    var statsTask = _repository.GetStatsAsync(userId);

    await Task.WhenAll(ordersTask, logsTask, statsTask); // BOOM 💥

    return new DashboardData(ordersTask.Result, logsTask.Result, statsTask.Result);
}
```

If you run this, you will immediately hit [this dreaded exception](https://learn.microsoft.com/en-us/ef/core/dbcontext-configuration/#avoiding-dbcontext-threading-issues):

> A second operation started on this context before a previous operation completed.
> This is usually caused by different threads using the same instance of DbContext, however instance members are not guaranteed to be thread safe.

**Why does this happen?**

The `DbContext` in EF Core is **not thread-safe**.
It is a stateful object designed to manage a single unit of work.
It maintains a "Change Tracker" to keep track of the entities you've loaded, and it wraps a single underlying database connection.

Database protocols (like the TCP stream for PostgreSQL or SQL Server) are generally synchronous at the connection level.
You cannot push two different SQL queries down the same wire at the exact same millisecond.
When you use `Task.WhenAll`, multiple threads try to grab that single connection simultaneously,
and EF Core steps in to throw the exception to prevent data corruption.

So, we have a dilemma: We want the speed of parallelism, but the `DbContext` forces us into sequential execution.

## The Solution

Since .NET 5, EF Core has provided a first-class solution for this exact scenario: `IDbContextFactory<T>`.

Instead of injecting a scoped instance of your context (which lives for the entire HTTP request),
you inject a factory that allows you to create lightweight, independent instances of `DbContext` on demand.

**_Note_**: While using the factory is the cleanest approach for Dependency Injection,
you can also manually instantiate the context (`using var context = new AppDbContext(options)`) if you have access to the `DbContextOptions`.

First, we need to register the factory in our `Program.cs`.

```csharp
// This registers IDbContextFactory<AppDbContext> as a Singleton (by default)
// It also registers AppDbContext as Scoped for ease of use elsewhere
builder.Services.AddDbContextFactory<AppDbContext>(options =>
{
    options.UseNpgsql(builder.Configuration.GetConnectionString("db"));
});
```

Now, let's refactor our slow dashboard endpoint.
Instead of injecting `AppDbContext`, we inject `IDbContextFactory<AppDbContext>`.

Inside our method, we spin up a dedicated task for each query.
Inside each task, we create a brand new context, execute the query, and then immediately dispose of it.

```csharp
using Microsoft.EntityFrameworkCore;

public class DashboardService(IDbContextFactory<AppDbContext> contextFactory)
{
    public async Task<DashboardDto> GetDashboardAsync(int userId)
    {
        // 1. Start the tasks (The queries start executing immediately upon invocation)
        var ordersTask = GetOrdersAsync(userId);
        var logsTask = GetSystemLogsAsync();
        var statsTask = GetUserStatsAsync(userId);

        // 2. Wait for all to complete
        await Task.WhenAll(ordersTask, logsTask, statsTask);

        // 3. Return results (using 'await Task.WhenAll' here unwraps the result cleanly)
        return new DashboardDto(
            await ordersTask,
            await logsTask,
            await statsTask
        );
    }

    private async Task<List<Order>> GetOrdersAsync(int userId)
    {
        // Create a fresh context for this specific operation
        await using var context = await contextFactory.CreateDbContextAsync();

        return await context.Orders
            .AsNoTracking()
            .Where(o => o.UserId == userId)
            .OrderByDescending(o => o.CreatedAt)
            .ThenByDescending(o => o.Amount)
            .Take(50)
            .ToListAsync();
    }

    private async Task<List<SystemLog>> GetSystemLogsAsync()
    {
        await using var context = await contextFactory.CreateDbContextAsync();

        return await context.SystemLogs
            .AsNoTracking()
            .OrderByDescending(l => l.Timestamp)
            .Take(50)
            .ToListAsync();
    }

    private async Task<UserStats?> GetUserStatsAsync(int userId)
    {
        await using var context = await contextFactory.CreateDbContextAsync();

        return await context.Users
            .Where(u => u.Id == userId)
            .Select(u => new UserStats { OrderCount = u.Orders.Count })
            .FirstOrDefaultAsync();
    }
}
```

**Key Concepts**

1. **Isolation**: Each task gets its own DbContext.
   This means they get their own database connection.
   There is no contention.
2. **Disposal**: Notice the await using.
   This is critical.
   As soon as the query is done, we want to dispose of that context and return the connection to the pool.

## The Benchmark

To prove this works, I built a small .NET 10 app using Aspire and PostgreSQL..
Since I'm running this locally, the absolute times are very low.
If I used a remote database, the times would be higher, but the speedup ratio would be similar.

**Sequential Execution**: ~36ms

<Image
  src="blogs/mnw_171/sequential_ef_queries_trace.png"
  width={1775}
  height={576}
  alt="A distributed trace showing sequential EF Core queries."
/>

The waterfall is painfully obvious here.
Each operation waits for the previous one to finish.

**Parallel Execution**: ~13ms

<Image
  src="blogs/mnw_171/parallel_ef_queries_trace.png"
  width={1775}
  height={576}
  alt="A distributed trace showing parallel EF Core queries."
/>

By using the parallel approach, the timeline compresses.
All three database spans start at the same time and complete together.

## Trade-offs & Conclusion

`IDbContextFactory` bridges the gap between EF Core's unit-of-work design and the reality of modern, parallel requirements.
It allows you to break out of the "one request, one thread" box without sacrificing safety.

However, use this pattern sparingly:

- **Connection pool starvation**: A single HTTP request now occupies 3 database connections simultaneously instead of 1.
  If you have high concurrency, you can easily exhaust your connection pool.
- **Context overhead**: If your queries are extremely fast (e.g., simple lookups by ID),
  the overhead of creating multiple contexts and tasks might make the parallel version slower than the sequential one.

Next time you are staring at a slow dashboard, don't reach for raw SQL immediately.
Check your awaits.
If they are lined up single-file, it might be time to introduce some parallelization.

---



<Sponsorships>

Have you ever thought, "How far can I really push Postgres with text?".
Watch [**Aiven's Elephant in the Room**](https://fandf.co/3XuqkFD) livestream for live-coding, real-world examples,
and practical insights on how developers can harness PostgreSQL's native text-search capabilities to build faster, smarter, and more efficient applications.
[**Access the playback here**](https://fandf.co/3XuqkFD).

Move faster and reduce risk.
Teleport's [**vault-free PAM cuts access provisioning time by 10x**](https://fandf.co/49pEyiq) by removing
static credentials and manual tickets, using short-lived certificates and zero-trust, just-in-time access.
Leave the vault behind — [**start for free**](https://fandf.co/49pEyiq).

</Sponsorships>

[**Vertical Slice Architecture**](vertical-slice-architecture) (VSA) seems like a breath of fresh air when you first encounter it.
You stop jumping between seven layers to add a single field.
You delete the dozens of projects in your solution.
You feel liberated.

But when you start implementing more complex features, the cracks begin to show.

You build a `CreateOrder` slice.
Then `UpdateOrder`.
Then `GetOrder`.
Suddenly, you notice the repetition.
The address validation logic is in three places.
The pricing algorithm is needed by both Cart and Checkout.

You feel the urge to create a `Common` project or `SharedServices` folder.
This is the most critical moment in your VSA adoption.

Choose wrong, and you'll reintroduce the coupling you were trying to escape.
Choose right, and you maintain the independence that makes VSA worthwhile.

Here's how I approach **shared code** in **Vertical Slice Architecture**.

## The Guardrails vs. The Open Road

To understand why this is hard, we need to look at what we left behind.

[**Clean Architecture**](clean-architecture-the-missing-chapter) provides strict guardrails.
It tells you exactly where code lives: Entities go in Domain, interfaces go in Application, implementations go in Infrastructure.
It's safe.
It prevents mistakes, but it also prevents shortcuts when they're appropriate.

[**Vertical Slice Architecture**](vertical-slice-architecture-structuring-vertical-slices) removes the guardrails.
It says, "Organize code by feature, not technical concern".
This gives you speed and flexibility, but it shifts the burden of discipline onto _you_.

So what can you do about it?

## The Trap: The "Common" Junk Drawer

The path of least resistance is to create a project (or folder) named `Shared`, `Common`, or `Utils`.

This is almost always a mistake.

Imagine a `Common.Services` project with an `OrderCalculationService` class.
It has a method for cart totals (used by Cart), another for historical revenue (used by Reporting),
and a helper for invoice formatting (used by Invoices).
Three unrelated concerns.
Three different change frequencies.
One class coupling them all together.

A `Common` project inevitably becomes a junk drawer for anything you can't be bothered to name properly.
It creates a tangled web of dependencies where unrelated features are coupled together because they happen to use the same helper method.

You've reintroduced the very coupling you tried to escape.

## The Decision Framework

When I hit a potential sharing situation, I ask three questions:

**1. Is this infrastructural or domain?**

Infrastructure (database contexts, logging, HTTP clients) almost always gets shared. Domain concepts need more scrutiny.

**2. How stable is this concept?**

If it changes once a year, share it. If it changes with every feature request, keep it local.

**3. Am I past the "Rule of Three"?**

Duplicating the same code once is fine.
However, creating three duplicates should raise an eyebrow.
Don't abstract until you hit three.

We solve this by refactoring our code.
Let's look at some examples.

## The Three Tiers of Sharing

Instead of binary "Shared vs. Not Shared," think in three tiers.

### Tier 1: Technical Infrastructure (Share Freely)

Pure plumbing that affects all slices equally: logging adapters, database connection factories, auth middleware,
the [**Result pattern**](functional-error-handling-in-dotnet-with-the-result-pattern), validation pipelines.

Centralize this in a `Shared.Kernel` or `Infrastructure` project.
Note that this can also be a folder within your solution.
It rarely changes due to business requirements.

```csharp
// ✅ Good Sharing: Technical Kernel
public readonly record struct Result
{
    public bool IsSuccess { get; }
    public string Error { get; }

    private Result(bool isSuccess, string error)
    {
        IsSuccess = isSuccess;
        Error = error;
    }

    public static Result Success() => new(true, string.Empty);
    public static Result Failure(string error) => new(false, error);
}
```

### Tier 2: Domain Concepts (Share and Push Logic Down)

This is one of the best places to share logic.
Instead of scattering business rules across slices, push them into entities and value objects.

Here's an example:

```csharp
// ✅ Good Sharing: Entity with Business Logic
public class Order
{
    public Guid Id { get; private set; }
    public OrderStatus Status { get; private set; }
    public List<OrderLine> Lines { get; private set; }

    public bool CanBeCancelled() => Status == OrderStatus.Pending;

    public Result Cancel()
    {
        if (!CanBeCancelled())
        {
            return Result.Failure("Only pending orders can be cancelled.");
        }

        Status = OrderStatus.Cancelled;
        return Result.Success();
    }
}
```

Now `CancelOrder`, `GetOrder`, and `UpdateOrder` all use the same business rules.
The logic lives in one place.

<div className="note-panel">
  This implies an important concept: **different vertical slices can share the
  same domain model.**
</div>

### Tier 3: Feature-Specific Logic (Keep It Local)

Logic shared between related slices, like `CreateOrder` and `UpdateOrder`, doesn't need to go global.
Create a `Shared` folder (there's an exception to every rule) within the feature:

```
📂 Features
└──📂 Orders
    ├──📂 CreateOrder
    ├──📂 UpdateOrder
    ├──📂 GetOrder
    └──📂 Shared
        ├──📄 OrderValidator.cs
        └──📄 OrderPricingService.cs
```

This also has a hiddene benefit.
If you delete the Orders feature, the shared logic goes with it.
No zombie code left behind.

Let's explore some advanced scenarios most people overlook.

## Cross-Feature Sharing

What about **sharing code between unrelated features** in Vertical Slice Architecture?

The `CreateOrder` slice needs to check if a customer exists.
`GenerateInvoice` needs to calculate tax.
Orders and Customers both need to format notification messages.

This doesn't fit neatly into a feature's `Shared` folder.
So where does it go?

**First, ask: do you actually need to share?**

Most cross-feature "sharing" is just data access in disguise.

If `CreateOrder` needs customer data, it queries the database directly.
It doesn't call into the Customers feature.
Each slice owns its data access.
The `Customer` entity is shared (it lives in `Domain`), but there's no shared service between them.

**When you genuinely need shared logic**, ask what it _is_:

- **Domain logic** (business rules, calculations) → `Domain/Services`
- **Infrastructure** (external APIs, formatting) → `Infrastructure/Services`

```csharp
// Domain/Services/TaxCalculator.cs
public class TaxCalculator
{
    public decimal CalculateTax(Address address, decimal subtotal)
    {
        var rate = GetTaxRate(address.State, address.Country);
        return subtotal * rate;
    }
}
```

Both `CreateOrder` and `GenerateInvoice` can use it without coupling to each other.

Before creating any cross-feature service, ask: could this logic live on a domain entity instead?
Most "shared business logic" is actually data access, domain logic that belongs on an entity, or premature abstraction.

If you need to trigger a side effect in another feature, I recommend using [**messaging and events**](event-driven-architecture-in-dotnet-with-rabbitmq).
Alternatively, the feature you want to call into can explore a facade ([**public API**](internal-vs-public-apis-in-modular-monoliths)) for that operation.

## When Duplication Is the Right Call

Sometimes "shared" code isn't actually shared.
It just looks that way.

```csharp
// Features/Orders/GetOrder
public record GetOrderResponse(Guid Id, decimal Total, string Status);

// Features/Orders/CreateOrder
public record CreateOrderResponse(Guid Id, decimal Total, string Status);
```

They're identical.
The temptation to create a `SharedOrderDto` is overwhelming.
Resist it.

Next week, `GetOrder` needs a tracking URL.
But `CreateOrder` happens before shipping, so there's no URL yet.
If you'd shared the DTO, you'd now have a nullable property that's confusingly empty half the time.

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

## The Practical Structure

Here's what a mature Vertical Slice Architecture project looks like:

```
📂 src
└──📂 Features
│   ├──📂 Orders
│   │   ├──📂 CreateOrder
│   │   ├──📂 UpdateOrder
│   │   └──📂 Shared          # Order-specific sharing
│   ├──📂 Customers
│   │   ├──📂 GetCustomer
│   │   └──📂 Shared          # Customer-specific sharing
│   └──📂 Invoices
│       └──📂 GenerateInvoice
└──📂 Domain
│   ├──📂 Entities
│   ├──📂 ValueObjects
│   └──📂 Services            # Cross-feature domain logic
└──📂 Infrastructure
│   ├──📂 Persistence
│   └──📂 Services
└──📂 Shared
    └──📂 Behaviors
```

- **Features** — Self-contained slices. Each owns its request/response models.
- **Features/[Name]/Shared** — Local sharing between related slices.
- **Domain** — Entities, value objects, and domain services. Shared business logic lives here.
- **Infrastructure** — Technical concerns.
- **Shared** — Cross-cutting behaviors only.

## The Rules

After building several systems this way, here's what I've landed on:

1. **Features own their request/response models.** No exceptions.

2. **Push business logic into the domain.** Entities and value objects are the best place to share business rules.

3. **Keep feature-family sharing local.** If only Order slices need it, keep it in `Features/Orders/Shared` (feel free to find a better name than `Shared`).

4. **Infrastructure is shared by default**. Database contexts, HTTP clients, logging. These are technical concerns.

5. **Apply the Rule of Three.** Don't extract until you have three real usages with identical, stable logic.

## Takeaway

Vertical Slice Architecture asks: "What feature does _this_ belong to?"

The shared code question is really asking: "What do I do when the answer is _multiple features_?"

Acknowledge that some concepts genuinely span features.
Give them a home based on their _nature_ (domain, infrastructure, or cross-cutting behavior).
Resist the urge to share everything just because you could.

The goal isn't zero duplication.
It's code that's easy to change when requirements change.

And requirements always change.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Tiger Data Launches Agentic Postgres on Tiger Cloud**](https://tsdb.co/milanj2)\
Tiger Data just made Postgres ready for the AI-native era with Agentic Postgres, now free to try.
With forkable databases for instant, zero-copy branches, hybrid search and APIs that let agents talk directly to your apps, it removes the complexity of building with AI.
Instead of stitching together multiple tools, developers get a unified Postgres based stack this is faster, safer, and cheaper.
Whether using Claude, Cursor, or custom agents, Tiger Cloud gives AI the infrastructure to branch, learn, and build safely.
[**Start building for free**](https://tsdb.co/milanj2)!

[**Augment Code's**](https://fandf.co/4pmt9Vn) new guide, [**_The Engineering Leader AI Imperative_**](https://fandf.co/4pmt9Vn),
features real frameworks to help you lead your engineering team to systematic transformation,
including 30% faster PR velocity, 40% reduction in merge times, and 10x task speed-ups across teams.
[**Learn from CTOs at Drata, Webflow, and Tilt**](https://fandf.co/4pmt9Vn) who've scaled AI across 100+ developer teams.
[**Read for free**](https://fandf.co/4pmt9Vn).

</Sponsorships>

**Let's be honest: We've all written this code.**

It's Monday morning, you have a deadline, and you need to implement a user registration feature.
It's simple enough: save the user, send a welcome email, and track the signup in your analytics dashboard.

You write this:

```csharp
public class UserService(
        IUserRepository userRepository,
        IEmailService emailService,
        IAnalyticsService analyticsService)
{
    public async Task RegisterUser(string email, string password)
    {
        var user = new User(email, password);
        await userRepository.SaveAsync(user);

        // 1. Directly coupled to email service (external API)
        await emailService.SendWelcomeEmail(user.Email);

        // 2. Directly coupled to analytics (this could be an external API)
        await analyticsService.TrackUserRegistration(user.Id);

        // What if we need to add more features?
        // This method will keep growing...
    }
}
```

It looks clean. It's readable. It works on your machine.

But this method is a **ticking time bomb**.

It assumes the "Happy Path" is the _only_ path.
It assumes the network is reliable, the email provider is up, and the analytics API is fast.
In production, none of these are guaranteed.

Thinking further, I'm sure you can imagine similar code in your own projects.
It might not be this exact scenario, but the pattern is common: a single method that orchestrates multiple side effects in a linear fashion.

Let's break down why this code is dangerous and how we can refactor it into a robust, event-driven architecture.

## The Hidden Dangers of the "God Method"

There are three major issues hiding in those ten lines of code.

### 1. Temporal Coupling (Latency)

When a user clicks "Register," they have to wait for:

1.  The Database **+**
2.  The SMTP Server **+**
3.  The Analytics API

If your analytics provider is having a bad day and takes 3 seconds to respond, **your user waits 3 seconds**.
You are punishing your user for the slowness of a background system they don't even care about.

### 2. The Partial Failure State

This is the **most critical risk**. Imagine this scenario:

1.  `SaveAsync(user)` succeeds. The user is in the DB.
2.  `SendWelcomeEmail` succeeds. The user gets an email.
3.  `TrackUserRegistration` throws a `503 Service Unavailable`.

**What happens now?**
If you wrap this in a transaction and rollback, you have deleted the user from the DB... **but you already sent them a welcome email.**
The user tries to log in, but they don't exist.
Now what?

If you _don't_ rollback, you have a user in your system that is missing from your analytics.
You have data inconsistency.

### 3. Violation of Single Responsibility (SRP)

You might argue that because we are using interfaces (`IEmailService`), we are decoupled.
That is true for _implementation details_, but false for _orchestration_.

The `UserService` currently has two reasons to change:

1.  **Core Domain Logic:** "We now require a username in addition to email."
2.  **Notification Policy:** "Marketing wants to send an SMS in addition to the Email."

The `UserService` should strictly be responsible for the **state change** (creating the user).
It should not be responsible for **orchestrating the side effects** of that change.

## Level 1: Logical Decoupling with Domain Events

The first step to fixing this is to invert the control.
Instead of the `UserService` _commanding_ other services to do things, it should simply _announce_ that something happened.

We can use [**Domain Events**](how-to-use-domain-events-to-build-loosely-coupled-systems) to achieve this.

Here is the refactored `UserService`:

```csharp
public class UserService(
        IUserRepository userRepository,
        IDomainEventDispatcher dispatcher,
        IUnitOfWork unitOfWork)
{
    public async Task RegisterUser(string email, string password)
    {
        // 1. Create the User Entity
        var user = new User(email, password);

        // 2. Capture the side effect as an event object
        var userRegisteredEvent = new UserRegisteredEvent(user.Id, user.Email);

        // 3. Add the entity to the repository
        await userRepository.AddAsync(user);

        // 4. Dispatch the event (Assuming in-process dispatching here for simplicity)
        // Note: Handlers for Email and Analytics are now completely separate classes.
        await dispatcher.Dispatch(userRegisteredEvent);

        await unitOfWork.SaveChangesAsync();
    }
}
```

The `UserService` is now stable.
Adding a "Loyalty Points" feature later doesn't require touching this method.
You just add a new handler for the `UserRegisteredEvent`.

**However, we haven't solved the reliability problem yet.**
If the process crashes immediately after `Dispatch` but before `SaveChangesAsync` completes, we might send an email for a user that failed to save.
Or, if we save first and dispatch later, we might save the user but lose the event if the server crashes.

## Level 2: Reliability with the Outbox Pattern

To fix this, we need **Atomicity**.
Atomicity means that a set of operations either all succeed or all fail together.

We need to guarantee that if the `User` is saved, the `UserRegisteredEvent` is also saved.

Enter the [**Outbox Pattern**](implementing-the-outbox-pattern).

Instead of publishing the event immediately to a message bus, we save the event to an `OutboxMessages` table in the **same database transaction** as the user.

Here is the complete implementation logic:

```csharp
public async Task RegisterUser(string email, string password)
{
    // 1. Create the Domain Event
    var user = new User(email, password);
    var domainEvent = new UserRegisteredEvent(user.Id, user.Email);

    // 2. Open a Transaction
    using var transaction = dbContext.Database.BeginTransaction();

    try
    {
        // 3. Save the User to the Users Table
        dbContext.Users.Add(user);

        // 4. Serialize the Event and Save to Outbox Table
        var outboxMessage = new OutboxMessage
        {
            Id = Guid.NewGuid(),
            Type = nameof(UserRegisteredEvent),
            Content = JsonSerializer.Serialize(domainEvent),
            OccurredOn = DateTime.UtcNow,
            ProcessedOn = null // Null means it hasn't been handled yet
        };

        dbContext.OutboxMessages.Add(outboxMessage);

        // 5. Commit BOTH changes atomically
        await dbContext.SaveChangesAsync();
        await transaction.CommitAsync();
    }
    catch
    {
        await transaction.RollbackAsync();
        throw;
    }
}
```

Now, a [**background worker**](scheduling-background-jobs-with-quartz-net) (running in a separate process) polls the `OutboxMessages` table.
It picks up the message and publishes it to your message bus (RabbitMQ, Azure Service Bus, etc.).

If the email service is down, the background worker just retries later.
**We have achieved At-Least-Once delivery.**

## Level 3: Distributed Consistency with Sagas

The Outbox pattern is perfect for side effects (fire-and-forget actions like emails).
But what if the subsequent action is **mandatory**?

**Scenario:** When a user registers, we _must_ create a crypto-wallet for them in the `WalletService`.
If the wallet creation fails (e.g., due to regulations), we cannot allow the user to exist in our system.

We can't just "retry later" if the `WalletService` says "Fraud Detected."
We need to **undo** the user creation.

This is a distributed transaction, and we handle it with the [**Saga Pattern**](implementing-the-saga-pattern-with-masstransit).
A Saga coordinates a series of steps.
If one fails, it executes **Compensating Transactions** to undo the previous work.

Here is how the failure scenario looks when using a [**Choreography-based Saga**](orchestration-vs-choreography):

<Image
  src="blogs/mnw_169/saga_sequence_diagram.png"
  width={1406}
  height={1860}
  alt="A Saga Sequence Diagram showing UserService creating a user, WalletService attempting to create a wallet, failing, and UserService deleting the user as a compensation action."
/>

Here's the step-by-step breakdown of the flow:

1.  **UserService:** Creates User → Publishes `UserCreated`
2.  **WalletService:** Listens to `UserCreated` → Tries to create wallet
    - _Failure:_ Wallet creation fails
    - _Action:_ Publishes `WalletCreationFailed`
3.  **UserService:** Listens to `WalletCreationFailed` → **Deletes/Deactivates the User**

This ensures **Eventual Consistency**.
The system might be inconsistent for a few seconds (the user exists without a wallet),
but it will eventually settle into a valid state (the user is removed).

## Summary: A Heuristic for Decision Making

You don't need Sagas for everything.
Over-engineering is just as bad as tight coupling.
Use this simple rule of thumb:

1.  **Is it a simple notification?** (Email, Analytics, Cache Invalidation)
    - **Use Domain Events + Outbox.** It's okay if it happens 5 seconds later.
2.  **Is it a critical business dependency?** (Payments, Inventory, Account Status)
    - **Use a Saga.** If step B fails, step A must be reverted.

Coupling isn't just about code structure.
It's about understanding and managing **failure boundaries**.
If your Analytics Service goes down, it shouldn't prevent a user from registering.
Build your systems to survive the unhappy path.

Hope this was helpful.

See you next week.

---



<Sponsorships>

Get a [**speedy and scalable enterprise ready login box**](https://fandf.co/3LW0tUq) customized to your design with
[**AuthKit from WorkOS**](https://fandf.co/3LW0tUq).
This developer-friendly and extensible solution is fully compatible with any app architecture and offers enterprise-grade security with modern auth standards.
[**Try AuthKit in your app now**](https://fandf.co/3LW0tUq).

[**Incident responders**](https://fandf.co/4pdf78l) from companies like NVIDIA, Netflix, Okta, and Anthropic just shared how they handle incidents in the AI era.
You missed it—but you can still catch up.
[**SEV0's**](https://fandf.co/4pdf78l) full session library is now on-demand, including:

- Why the best teams declare MORE incidents (not fewer—and what that unlocks)
- The human factors that actually determine incident outcomes (spoiler: it's not just your tooling)
- How AI coding is reshaping on-call (with real production examples)

[**You can revisit these conversations and many more here**](https://fandf.co/4pdf78l).

</Sponsorships>

C# has always been a bit ceremony-heavy, and we all know it.
Even the simplest "Hello World" program traditionally needed a solution file, a project file,
and enough boilerplate to make you wonder if you should've just used a scripting language instead.

Well, Microsoft finally heard us.
With .NET 10, they've introduced [**file-based apps**](run-csharp-scripts-with-dotnet-run-app-no-project-files-needed).
And honestly, it's about time.

## What are File-based Apps?

The idea is simple: write your C# code in a single `.cs` file and run it directly. That's it.

No need to set up a whole project structure for that quick utility script you need to parse some CSV files or test an API endpoint.

You get to keep everything that makes C# great: the **type safety**, the **performance**, the **rich standard library**.
But now you can use it for those throwaway scripts where setting up a full project would've been overkill.
And yes, you can still **reference NuGet packages**, **reference other C# projects**, target specific SDKs,
and configure project properties, all from within that single file using special directives that start with `#:`.

The feature builds on **top-level statements** (remember those from C# 9?) and takes them to their logical conclusion.
If we're already letting people skip the class and `Main` method ceremony, why not let them skip the project ceremony too?

## Getting Started with File-based Apps

Let's say you want to quickly check what day of the week a specific date falls on.
Create a file called `date-checker.cs`:

```csharp
var targetDate = new DateTime(2025, 12, 31);
Console.WriteLine($"New Year's 2025 falls on a {targetDate.DayOfWeek}");
Console.WriteLine($"That's {(targetDate - DateTime.Today).Days} days from now");
```

Run it with:

```bash
dotnet run date-checker.cs
```

The first time you run this, the CLI does some behind-the-scenes magic.
It creates a virtual project, compiles your code, and caches everything.
Subsequent runs are nearly instant because it's smart enough to know when nothing has changed.

## Real-world Example: Quick Data Processing

Here's where things get interesting.
Say you need to quickly process some JSON data and generate a report.

Let's do something practical with `System.Text.Json` and `CsvHelper`:

```csharp {1}
#:package CsvHelper@33.1.0
using System.Text.Json;
using CsvHelper;
using System.Globalization;

var json = await File.ReadAllTextAsync("sales_data.json");
var sales = JsonSerializer.Deserialize<List<SaleRecord>>(json);

var topProducts = sales
    .GroupBy(s => s.Product)
    .Select(g => new {
        Product = g.Key,
        TotalRevenue = g.Sum(s => s.Amount),
        UnitsSold = g.Count()
    })
    .OrderByDescending(p => p.TotalRevenue)
    .Take(10);

using var writer = new StreamWriter("top_products.csv");
using var csv = new CsvWriter(writer, CultureInfo.InvariantCulture);
csv.WriteRecords(topProducts);

Console.WriteLine("Report generated! Check top_products.csv");

record SaleRecord(string Product, decimal Amount, DateTime Date);
```

Notice how we're mixing package references, async operations, LINQ, and record types, all in a single file that reads like a cohesive script.
This is the kind of thing you'd typically reach for Python for, but now you can stay in C# land.

## Building Something More Ambitious with Aspire

You can actually create an **Aspire AppHost** in a single file, which is pretty wild when you think about it:

```csharp
#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.AppHost@13.0.0

var builder = DistributedApplication.CreateBuilder(args);

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

var postgres = builder.AddPostgres("postgres")
    .WithDataVolume()
    .AddDatabase("tododb");

var todoApi = builder.AddProject<Projects.TodoApi>("api")
    .WithReference(cache)
    .WithReference(postgres);

builder.AddNpmApp("frontend", "../TodoApp")
    .WithReference(todoApi)
    .WithReference("api")
    .WithHttpEndpoint(env: "PORT")
    .WithExternalHttpEndpoints();

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

With the `#:sdk Aspire.AppHost.Sdk@13.0.0` directive, your single file becomes a full orchestrator for a distributed application.
You're defining infrastructure, wiring up dependencies, and setting up a complete development environment, all without creating a project file.
It's particularly useful when you're prototyping architectures or need to quickly spin up a test environment.

## Migrating to a Full Project

Eventually, some scripts outgrow their single-file roots.
Maybe you need to split things into multiple files, or maybe you want proper IDE support for debugging.
The transition is painless:

```bash
dotnet project convert MyUtility.cs
```

This generates a proper project structure while preserving all your package references and SDK choices.
Your code moves to `Program.cs`, and you get a `.csproj` that reflects all those `#:` directives you were using.

## Current Limitations

Right now, it's strictly single-file.
If you need **multiple files**, you'll have to [wait for .NET 11](https://github.com/dotnet/sdk/issues/48174) or convert to a full project.
Of course, you can still reference other projects or packages, but the main script has to be in one file.

The caching mechanism can occasionally get confused if you're rapidly iterating on package versions.
And while the IDE support is getting better, it's not quite at the same level as full projects yet, especially for IntelliSense with dynamically referenced packages.

But for what it's designed to do (make C# approachable for scripting scenarios), it works remarkably well.
You can use it for **build scripts**, **data migration one-offs**, quick API tests, or even teaching C# without overwhelming beginners with project structure.

## Where This Leaves Us

**File-based apps** feel like C# finally acknowledging that not every piece of code needs to be an enterprise application.
Sometimes you just need to parse a log file, sometimes you want to quickly test an algorithm,
and sometimes you're teaching someone programming and don't want to explain what a solution file is on day one.

The feature doesn't revolutionize C# development, but it **fills a gap** that's been annoying developers for years.
If you've been keeping a folder of scripts for quick tasks because C# felt too heavy, maybe it's time to give your favorite language another shot.

After all, the best language for a quick script is the one you already know, and now C# makes that argument a lot more compelling.

---



<Sponsorships>

[**AI-powered engineering at scale**](https://fandf.co/4oCqG8Y)\
Leading engineering teams have moved beyond scattered tool adoption to systematic transformation:
30% faster PR velocity, 40% reduction in merge times, and 10x task speed-ups across teams.
[**Augment Code's new playbook shows you how**](https://fandf.co/4oCqG8Y), with real frameworks from CTOs at Drata, Webflow, and Tilt who've scaled AI across 100+ developer teams.
[**Read for free**](https://fandf.co/4oCqG8Y).

[**JetBrains ReSharper**](https://open-vsx.org/extension/JetBrains/resharper-code) is now available on the Open VSX Registry,
making it easy for Cursor, Windsurf, or VS Codium users to boost their C# productivity.
To get started, search for "ReSharper" in the Extensions view.
[**Learn more**](https://open-vsx.org/extension/JetBrains/resharper-code)

</Sponsorships>

Distributed systems are unreliable by nature.

I always recommend reading about the [Fallacies of Distributed Computing](https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing) to understand the common pitfalls.

One of the key challenges is ensuring that messages are processed **exactly once**.
Theoretically, that's impossible to guarantee in most systems.
I won't dive into the [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem) or the
[Two Generals Problem](https://en.wikipedia.org/wiki/Two_Generals%27_Problem) here, but suffice to say:

- Messages can arrive out of order
- Messages can be duplicated
- Deliveries can be delayed

If you design your system assuming every message will be processed exactly once, you're setting yourself up for subtle data corruption.

But we can design our system to apply side effects **exactly once** using the [**Idempotent Consumer**](idempotent-consumer-handling-duplicate-messages) pattern.

Let's unpack what can go wrong, how brokers help with idempotency, and how you can build an idempotent consumer in .NET.

## What Can Go Wrong When Publishing

Let's say your service publishes an event when a new note is created:

```csharp
await publisher.PublishAsync(new NoteCreated(note.Id, note.Title, note.Content));
```

We don't have to worry about the specific implementation of `publisher` or the message broker here.
It could be RabbitMQ, SQS, Azure Service Bus, etc.

Now imagine:

- The publisher sends the message to the broker
- The broker stores it and sends an ACK
- **Network glitch**: the ACK never reaches the producer
- Producer times out and **retries** the publish
- The broker now has two `NoteCreated` events

From the producer's perspective, it "fixed" a timeout.
But from the consumer's perspective, it received two events for the same note creation.

<Image
  src="blogs/mnw_167/distributed_messaging_with_error.png"
  width={1991}
  height={1296}
  alt="Distributed messaging with network error causing duplicate messages."
/>

And that's just one failure path.
You can also get duplicates from:

- Broker redeliveries
- Consumer failures + retries

So even if you do everything "right" on the publisher, the **consumer still has to be defensive**.

## Publisher-Side Idempotency (Let the Broker Handle It)

Many message brokers already support idempotent publishing via message deduplication if you include a unique message ID.
[**Azure Service Bus**](messaging-made-easy-with-azure-service-bus), for instance, can detect duplicates and ignore re-publishes for the same message ID within a configured window.
[**Amazon SQS**](complete-guide-to-amazon-sqs-and-amazon-sns-with-masstransit) and other brokers also offer similar guarantees.

You don't need to reinvent this logic in your application.
The key is to assign each message a stable identifier that uniquely represents the logical event you're sending.

For example, when publishing a NoteCreated event:

```csharp {3}
var message = new NoteCreated(note.Id, note.Title, note.Content)
{
    MessageId = Guid.NewGuid() // or you can use note.Id
};

await publisher.PublishAsync(message);

```

If the network drops after you send the message, your app might retry.
But when the broker sees the same `MessageId`, it knows this is a duplicate and safely discards it.
You get deduplication without any custom tracking tables or extra state in your service.

This broker-level idempotency solves a large class of **producer-side issues**: network retries, transient failures, and duplicated publishes.

What it doesn't handle are **consumer retries**, which happen when messages are redelivered or your service crashes mid-processing.

That's where the idempotent consumer pattern comes in.

## Implementing an Idempotent Consumer in .NET

Here's an example of an idempotent consumer for a `NoteCreated` event:.

```csharp
internal sealed class NoteCreatedConsumer(
    TagsDbContext dbContext,
    HybridCache hybridCache,
    ILogger<Program> logger) : IConsumer<NoteCreated>
{
    public async Task ConsumeAsync(ConsumeContext<NoteCreated> context)
    {
        // 1. Check if we've already processed this message for this consumer
        if (await dbContext.MessageConsumers.AnyAsync(c =>
                c.MessageId == context.MessageId &&
                c.ConsumerName == nameof(NoteCreatedConsumer)))
        {
            return;
        }

        var request = new AnalyzeNoteRequest(
            context.Message.NoteId,
            context.Message.Title,
            context.Message.Content);

        try
        {
            using var transaction = await dbContext.Database.BeginTransactionAsync();

            // 2. Deterministic processing: derive tags from note content
            var tags = AnalyzeContentForTags(request.Title, request.Content);

            // 3. Persist tags
            var tagEntities = tags.Select(ProjectToTagEntity(request.NoteId)).ToList();
            dbContext.Tags.AddRange(tagEntities);

            // 4. Record that this message was processed
            dbContext.MessageConsumers.Add(new MessageConsumer
            {
                MessageId = context.MessageId,
                ConsumerName = nameof(NoteCreatedConsumer),
                ConsumedAtUtc = DateTime.UtcNow
            });

            await dbContext.SaveChangesAsync();
            await transaction.CommitAsync();

            // 5. Update cache
            await CacheNoteTags(request, tags);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Error analyzing note {NoteId}", request.NoteId);
            throw;
        }
    }
}
```

This is a typical idempotent consumer with a few important details.

**1. The Idempotency Key**

```csharp
if (await dbContext.MessageConsumers.AnyAsync(c =>
        c.MessageId == context.MessageId &&
        c.ConsumerName == nameof(NoteCreatedConsumer)))
{
    return;
}
```

You use:

- `MessageId` from the transport (`context.MessageId`)
- `ConsumerName` (so multiple consumers can safely process the same message)

If a duplicate message arrives, you short-circuit and do nothing.

What's also important here is having a **unique constraint** on `(MessageId, ConsumerName)` in the `MessageConsumers` table to prevent
[**race conditions**](solving-race-conditions-with-ef-core-optimistic-locking).
So even if you have concurrent processing of the same message, only one will succeed in inserting the record.

**2. Atomic Side Effects + Idempotency Record**

The processing and storing the message consumer record happen **in the same transaction**:

```csharp {1,10}
using var transaction = await dbContext.Database.BeginTransactionAsync();

// write tags
dbContext.Tags.AddRange(tagEntities);

// write message-consumer record
dbContext.MessageConsumers.Add(new MessageConsumer { ... });

await dbContext.SaveChangesAsync();
await transaction.CommitAsync();
```

Why this matters:

- If processing fails, there is no entry in `MessageConsumers`, so the message can be retried
- If processing succeeds, both the tags and the `MessageConsumer` row are committed together
- You never end up in a state where the work is done but the message is not marked as processed, or vice versa

This is the core of idempotency:

> Do this work exactly once per message ID, even under retries.

**3. Handling At-Least-Once Delivery**

Most realistic setups are **at-least-once**:

- Consumer processes message
- ACK fails / times out
- Broker redelivers
- Your code runs again

With this pattern, the second run hits the `MessageConsumers` table and returns early.

No duplicate side effects.

This works, except for one caveat...

## Deterministic vs Non-Deterministic Handlers

What happens when your handler calls something _outside_ the database?
An email API, a payment gateway, or a background job queue?

These are all common side effects that need to be idempotent too.

Those calls sit outside your transaction boundary.
Your database might commit successfully, but if the network hiccups before the external service responds, you can't tell if the action happened or not.
On retry, your consumer might send another email or charge the credit card twice.

You've now crossed into the messy territory of non-deterministic handlers: operations that can't be repeated safely.

There are two main strategies to deal with this.

**1. Use an Idempotency Key in the External Call**

If the external service supports it, pass a stable identifier, like the message's `MessageId` with every request.
Many APIs, including payment processors and email platforms, let you specify an idempotency key header.
The service ensures that identical requests with the same key only execute once.

For example:

```csharp {6}
await emailService.SendAsync(new SendEmailRequest
{
    To = user.Email,
    Subject = "Welcome!",
    Body = "Thanks for signing up.",
    IdempotencyKey = context.MessageId
});

```

Even if the request is retried, the provider will recognize the key and skip the duplicate.
This is the simplest and most reliable approach, if your external dependency supports it.

**2. Store the Intent Locally**

If the external service doesn't support idempotency keys, you can simulate it.
Store a **record of the intended action** in your database before calling the external system.
For example, create a `PendingEmails` table that records which messages should be sent, keyed by message ID or user ID.

A background process can later read these pending records and perform the action once.
This makes the process deterministic, but at the cost of more complexity, extra tables, and background workers.
It's often overengineering unless the side effect is critical or irreversible, like payments or account provisioning.

The trade-off comes down to confidence.
If repeating the action has real consequences, introduce idempotency explicitly.
If not, retrying the operation might be acceptable.

## When Idempotent Consumer Isn't Needed

Not every consumer needs the overhead of idempotency checks.
If your operation is already naturally idempotent, you can often skip the extra table and transaction logic.

Updating a projection, setting a status flag, or refreshing a cache are all examples of deterministic actions that can safely run multiple times.
For instance, "set user's status to Active" or "rebuild the read model" are operations that overwrite state rather than append to it.

Some handlers also use precondition checks to avoid duplication.
If the handler updates an entity, it can first check whether that entity is already in the desired state and return early.
That simple guard clause can be enough.

Don't blindly apply the **Idempotent Consumer** pattern everywhere.
Apply it where it protects you from real harm, where duplicate processing causes financial or data inconsistencies.

For everything else, **simpler is better**.

## Takeaway

Distributed systems are unpredictable.
Retries, duplicates, and partial failures are part of normal operation.
You can't avoid them, but you can design your system so they don't impact you as much.

Use your broker's built-in **message deduplication** to prevent duplicates from the producer side.
For the consumer side, apply the **Idempotent Consumer** pattern to ensure side effects happen once, even under retries.
Keep the record of processed messages and the actual side effect in the same transaction.

Not every message handler needs this.
If your consumer is naturally idempotent or can short-circuit with a simple precondition, skip the extra complexity.
But for anything that modifies persistent state or calls external systems, idempotency isn't optional, it's the only way to keep your system consistent.

Build your consumers to tolerate retries.
And your distributed system will be that much more reliable.
The interesting part is that once you understand this principle, you start seeing it everywhere in real-world systems.

If you want to dive deeper into messaging patterns and learn how this is implemented in a production-grade system,
check out my [**Modular Monolith Architecture**](/modular-monolith-architecture) course.
We'll build a full-featured application with distributed messaging, CQRS, and DDD patterns from scratch.

Hope this was helpful.

---



<Sponsorships>

[**State of Designer-Developer Collaboration Survey 2025**](https://progress.co1.qualtrics.com/jfe/form/SV_40mWhGrQAktLQbQ?Source=Newsletters)\
Your perspective matters!
Join other professionals in the State of Designer-Developer Collaboration 2025: Workflows, Trends and AI survey to share
how AI and new workflows are impacting collaboration—and be among the first to see the key findings.
[**Start the 2025 Survey**](https://progress.co1.qualtrics.com/jfe/form/SV_40mWhGrQAktLQbQ?Source=Newsletters)!

[**Power Up Your Engineering Team with Kilo Code**](https://fandf.co/3Wg5GbV)\
Built by GitLab's co-founder, open-source Kilo Code has rocketed from zero to 400,000 downloads in under 6 months.
Transparent pricing across 500+ models means no hidden fees, just pay-as-you-go at exact list prices.
And now, with their Teams and Enterprise editions, you can enjoy centralized billing and seamless collaboration with the security,
compliance, and control your company needs to deploy AI assistants at scale.
[**Start Building**](https://fandf.co/3Wg5GbV)

</Sponsorships>

If you've ever worked with databases, you know about `LEFT JOIN` (and conversely `RIGHT JOIN`).
It's one of those things we use often, if not all the time.
But in Entity Framework Core, doing a left join has always been... well, a bit of a pain.

I like joins that read like what they do.
Unfortunately, until now, LINQ didn't have a straightforward way to express left/right joins.
You had to jump through hoops with `GroupJoin` and `DefaultIfEmpty`, which made the code harder to read and maintain.

But **.NET 10** finally fixes this with the brand new `LeftJoin` and `RightJoin` methods.

## What's a LEFT JOIN (in plain words)?

A **LEFT JOIN** returns **all rows from the left side** and the **matching rows from the right side**.
If there's **no match**, the right side is **null**.
Why we use it: to keep "owners" even when they have **no related rows** (e.g., show all products even if some don't have a review).

<figure className="figure-center bordered">
  <Image
    src="blogs/mnw_166/left_join.gif"
    width={988}
    height={554}
    alt="Animated left join."
  />
  <figcaption>
    Source: [Data
    School](https://dataschool.com/how-to-teach-people-sql/left-right-join-animated/)
  </figcaption>
</figure>

## The Old Way (`GroupJoin` + `DefaultIfEmpty`)

Before .NET 10, a left join in LINQ needed a **group join** (`GroupJoin`), then `DefaultIfEmpty` to keep left rows with no match.
It worked, but the intent was buried in noise.

There are two ways you could write it: **query syntax** and **method syntax**.

### Query syntax

```csharp
var query =
    from product in dbContext.Products
    join review in dbContext.Reviews on product.Id equals review.ProductId into reviewGroup
    from subReview in reviewGroup.DefaultIfEmpty()
    orderby product.Id, subReview.Id
    select new
    {
        ProductId = product.Id,
        product.Name,
        product.Price,
        ReviewId = (int?)subReview.Id ?? 0,
        Rating = (int?)subReview.Rating ?? 0,
        Comment = subReview.Comment ?? "N/A"
    };
```

Here's the SQL generated by EF Core for the above query:

```sql
SELECT
    p."Id" AS "ProductId",
    p."Name",
    p."Price",
    COALESCE(r."Id", 0) AS "ReviewId",
    COALESCE(r."Rating", 0) AS "Rating",
    COALESCE(r."Comment", 'N/A') AS "Comment"
FROM "Products" AS p
LEFT JOIN "Reviews" AS r ON p."Id" = r."ProductId"
ORDER BY p."Id", COALESCE(r."Id", 0)
```

### Method syntax

```csharp
var query = dbContext.Products
    .GroupJoin(
        dbContext.Reviews,
        product => product.Id,
        review => review.ProductId,
        (product, reviewList) => new { product, subgroup = reviewList })
    .SelectMany(
        joinedSet => joinedSet.subgroup.DefaultIfEmpty(),
        (joinedSet, review) => new
        {
            ProductId = joinedSet.product.Id,
            joinedSet.product.Name,
            joinedSet.product.Price,
            ReviewId = (int?)review!.Id ?? 0,
            Rating = (int?)review!.Rating ?? 0,
            Comment = review!.Comment ?? "N/A"
        })
    .OrderBy(result => result.ProductId)
    .ThenBy(result => result.ReviewId);
```

Why this works: `GroupJoin` matches rows, `DefaultIfEmpty` inserts a single **default** (null) when no matches exist, so the left row still appears.
We then **flatten** with `SelectMany`.

I think we can all agree that this is way too verbose for something as common as a left join.

## The New Way in EF 10: `LeftJoin`

Now we can write what we mean.
`LeftJoin` is **first-class LINQ** and EF Core translates it to a **LEFT JOIN** in SQL.

```csharp
var query = dbContext.Products
    .LeftJoin(
        dbContext.Reviews,
        product => product.Id,
        review => review.ProductId,
        (product, review) => new
        {
            ProductId = product.Id,
            product.Name,
            product.Price,
            ReviewId = (int?)review.Id ?? 0,
            Rating = (int?)review.Rating ?? 0,
            Comment = review.Comment ?? "N/A"
        })
    .OrderBy(x => x.ProductId)
    .ThenBy(x => x.ReviewId)
```

The generated SQL is identical to the previous example.

Why this is better:

- **Intent is clear**: you see `LeftJoin`, you know what to expect.
- **Less code**, fewer moving parts (no `GroupJoin`, no `DefaultIfEmpty`, no `SelectMany`).
- **Same result**: all products kept, reviews may be null.

<div className="note-panel">
  **Note**: At the time of writing this article, C# **query syntax** (`from …
  select …`) doesn't have a `left join` or `right join` keyword yet. You should
  use the method syntax shown above.
</div>

## Also New: `RightJoin`

`RightJoin` keeps **all rows from the right side** and only matching rows from the left.
EF Core translates it to **RIGHT JOIN**.
It's handy when the "must keep" side is the **second** sequence.

Conceptually:

```csharp
var query = dbContext.Reviews
    .RightJoin(
        dbContext.Products,
        review => review.ProductId,
        product => product.Id,
        (review, product) => new
        {
            ProductId = product.Id,
            product.Name,
            product.Price,
            ReviewId = (int?)review.Id ?? 0,
            Rating = (int?)review.Rating ?? 0,
            Comment = review.Comment ?? "N/A"
        });
```

Why use `RightJoin`: when your reporting starts from **Reviews** (keep all), and bring in matching **Products** if they exist.

Here's the generated SQL:

```sql
SELECT
    p."Id" AS "ProductId",
    p."Name",
    p."Price",
    COALESCE(r."Id", 0) AS "ReviewId",
    COALESCE(r."Rating", 0) AS "Rating",
    COALESCE(r."Comment", 'N/A') AS "Comment"
FROM "Reviews" AS r
RIGHT JOIN "Products" AS p ON r."ProductId" = p."Id"
```

## Wrapping Up

Think about how often you need left joins.
Showing all users with optional profile settings.
All products with optional reviews.
All orders with optional shipping info.
It's everywhere!

Before, developers would sometimes skip the proper left join and do two separate queries instead.
Or worse, they'd use an inner join and miss data.
Now there's no excuse - it's just as easy as any other LINQ method.

A few quick tips when writing LINQ queries:

- In the projection, guard nullable side: `review.Comment ?? "N/A"`
- Keep projections **small** to avoid pulling more columns than needed
- Add indexes on the **join keys** for better query plans

That's it.
With `LeftJoin` and `RightJoin`, the code finally matches the mental model.

See you next Saturday.

---



<Sponsorships>

Big news: [**Aiven Inkless**](https://bit.ly/493dYLV), the first production-ready open-source implementation of Diskless Kafka, is now GA.
It eliminates costly broker replication by writing directly to cloud object storage, making Kafka leaner, faster, and up to [**80% cheaper to run**](https://bit.ly/4njwVxa).
Try it now and see how the future of Kafka is diskless: [**aiven.io/inkless**](https://bit.ly/493dYLV)

[**Master Your SDLC: Delivering Enterprise-Ready APIs**](https://bit.ly/477agzl)\
Join **Shashank Awasthi** (Postman) and **Allen Helton** (Momento) for an exclusive fireside chat on Thursday,
Nov 6, 2025 (10am PST / 1pm EST / 6pm GMT).

- Get strategic guidance on structuring your SDLC to deliver APIs that are consistent, compliant, and enterprise-ready.
- Gain insight into how to close critical lifecycle gaps, prevent spec drift, and embed security from the start.
- Learn how to deliver secure, predictable, and future-proof APIs — trusted by both humans and AI agents.

[**Register now**](https://bit.ly/477agzl)

</Sponsorships>

About six or seven years ago, I went through an interview for a mid-level .NET role.

One of the questions has stayed with me ever since:

> A user clicks a button on the UI to generate an Excel or PDF report.
> The report generation takes around five minutes (time can be arbitrary).
> The user has to wait for it to finish.
> How would you optimize this flow?

At the time, I focused on what I knew best: **performance**.
I started thinking about how to make the report generation faster.
Maybe I could optimize the SQL queries, reduce data transformations, or [**cache**](caching-in-aspnetcore-improving-application-performance) parts of the result.
If I could get the process down from five minutes to one, that felt like a big win.

But even if I made it five times faster, the user still had to wait.
If the browser crashed, they lost everything.
If the network dropped, the process stopped.
If they closed the tab, all progress was gone.

It wasn't really a performance issue at all, it was a **design issue**.

## What I Missed Back Then

Looking back, I realize I was **stuck** in the mindset of "make the code faster".
Not that there's anything wrong with that, **performance optimization is a valuable skill**.
What I didn't see immediately was the **bigger problem**.
The app was doing all this work **synchronously**, holding the user hostage until it finished.
I did eventually figure it out, with a few nudges from the interviewer.

<Image src="blogs/mnw_165/sync_reporting_flow.png" width={2258} height={1201} />

The better question wasn't _"How can I make this faster?"_

It was _"Why is the user waiting in the first place?"_

If something takes minutes (or hours, days) to complete, it shouldn't block the user.
It should happen in the **background**, out of the **main request flow**, while the user moves on with their work.

Still, don't forget to optimize the code itself.
Database queries, data processing, and file generation all matter.
Maybe there's a missing index, an inefficient loop, or a better library for creating Excel files.
But those optimizations are just part of the solution, not the whole picture.

## How I'd Solve It Today

Today, I'd still start with the same UI button.
The user clicks "Generate Report," but instead of waiting, the **backend accepts the request**,
saves it somewhere (maybe as a job record in a database), and **returns right away**.
This is the essence of building [**asynchronous APIs**](building-async-apis-in-aspnetcore-the-right-way).
The job is then picked up by a background worker.

The worker can be a [**hosted service**](running-background-tasks-in-asp-net-core),
a [**Quartz job**](scheduling-background-jobs-with-quartz-in-dotnet-advanced-concepts),
or even an [**AWS Lambda Function**](building-fast-serverless-apis-with-minimal-apis-on-aws-lambda) triggered by a queue message.
It handles the heavy lifting: pulling the data, building the file, and uploading it to storage like S3 or Azure Blob.

Once the report is ready, the worker updates the job status to "completed" and notifies the user.
That could be an email with a download link or a real-time SignalR message that shows up in the app.
The link points to the stored report, served securely from the backend.

<Image
  src="blogs/mnw_165/async_reporting_flow.png"
  width={3566}
  height={2033}
/>

Now, the user isn't waiting on a long-running HTTP request.
The server isn't holding open connections for minutes.
**If something fails, it can be retried automatically**.
You also have the option to **track progress** or **cancel** the job if needed.
And if a hundred users request reports at once, the system can scale without locking up.

The experience feels faster, even if the actual report generation time hasn't changed.
Because in the end, users don't care about performance metrics, they care about responsiveness.

## Why I Still Use This Question

A few years later, I started using this exact question when interviewing other developers.
Not to trick anyone, but because it reveals how people think.

Some candidates go straight to optimizing code and queries, just like I did back then.
This is a good sign that they know their way around performance tuning.
I can proceed with further technical questions around **algorithms**, **data structures**, or **database optimization**.

Others pause for a moment and start thinking about user experience, **background processing**, and **fault tolerance**.
That's when the real conversation begins: queues, retries, notifications, secure file sharing, etc.
There are so many ways you can spin off this one scenario into a broader system design discussion.

There's **no single right answer**.
But there's a big difference between someone who focuses only on _code_ and someone who can design a _scalable system_.

## The Lesson

When I first heard this question, I thought about making the code faster.
Now I think about making the experience better.

Optimizing a query or loop can help, but it doesn't fix waiting, failures, or scalability.
If many users start the same report at once, a synchronous design breaks down fast.
An asynchronous flow keeps the system responsive and resilient, no matter the load.

That shift from optimizing functions to designing scalable systems is the difference between a good developer and a great one.

If you want to go deeper into building systems that scale, my [**Clean Architecture course**](/pragmatic-clean-architecture) walks you through exactly that.
You'll learn how to structure applications, separate concerns, and design systems that grow without breaking.

Hope this was helpful.

See you next week.

---



<Sponsorships>

Generative AI, governance, and strategic scaling are transforming the software development lifecycle for engineering leaders.
Here are 3 key findings from Postman's [**State of the API Report**](https://bit.ly/4nBsvTo):

- 89% of devs use AI, but few design for agents.
- 65% of organizations now generate revenue from APIs.
- 51% cite unauthorized AI agent access as a top security risk

[**Get Postman's 90-Day AI Readiness Playbook**](https://bit.ly/46MGPkG)

SambaNova announced [**Agents**](https://bit.ly/4hbWmze): an open source framework for producing detailed reports and analysis.
What used to take hours across 5-8 different apps — research, analysis, formatting, and file creation —
can now happen in a single prompt powered by [**SambaCloud**](https://bit.ly/3J3Iqe8).
Generate deep research reports, build deployable html pages, analyze data, and automatically create Jira tickets.
[**Check out Agents today**](https://bit.ly/4hbWmze)!

</Sponsorships>

Starting a new .NET project is always exciting.
But it's also easy to skip the groundwork that makes a project scalable and maintainable.

Before you write your first line of business logic, there are a few key setup steps that make your life (and your teammates) much easier later on.

Here's how I usually set up a new .NET project in **six simple steps**.

## 1. Enforce a Consistent Code Style

The first thing I add is an `.editorconfig` file.

This file ensures everyone on your team uses the same formatting and naming conventions, reducing inconsistent indents or random naming rules.

You can create one directly in Visual Studio:

<div class="centered">
  <Image src="blogs/mnw_164/add_editorconfig.png" width={654} height={190} />
</div>

The default configuration is a great start.
But you can customize it further to fit your team's preferences.

Place it at the **solution root** so all projects follow the same rules.
You can still override specific settings in subfolders if needed by placing an `.editorconfig` file there.

Here are two sample `.editorconfig` files you can use:

- [From the .NET runtime repo](https://github.com/dotnet/runtime/blob/main/.editorconfig)
- [Created by me for general .NET projects](https://gist.github.com/m-jovanovic/417b7d0a641d7dd7d1972550fba298db)

## 2. Centralize Build Configuration

Next, I add a `Directory.Build.props` file to the solution root.
This file lets you define build settings that apply to every project in the solution.

Here's an example:

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

This keeps your `.csproj` files clean and consistent, since there's no need to repeat these properties in every project.

If you later want to enable static analyzers or tweak build options, you can do it once here.

What's cool about this is your `.csproj` files become basically empty, with only NuGet package references most of the time.

## 3. Centralize Package Management

As your solution grows, managing NuGet package versions across multiple projects gets painful.

That's where [**central package management**](central-package-management-in-net-simplify-nuget-dependencies) helps.

Create a file named `Directory.Packages.props` at the root:

```xml
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="SonarAnalyzer.CSharp" Version="10.15.0.120848" />
  </ItemGroup>
</Project>
```

Now, when you reference a NuGet package in your project, you don't specify the version.
You can only use the package name like this:

```xml
<PackageReference Include="Microsoft.AspNetCore.OpenApi" />
```

All versioning is handled centrally.
This makes dependency upgrades trivial and avoids version drift between projects.

You can still override versions in individual projects if needed.

## 4. Add Static Code Analysis

[**Static code analysis**](improving-code-quality-in-csharp-with-static-code-analysis) helps catch potential bugs and maintain code quality.
.NET has a set of built-in analyzers, but I like to add **SonarAnalyzer.CSharp** for more comprehensive checks.

Let's install **SonarAnalyzer.CSharp** to catch potential code issues early:

```powershell
Install-Package SonarAnalyzer.CSharp
```

Add it as a global package reference inside your `Directory.Build.props`:

```xml
<ItemGroup>
  <PackageReference Include="SonarAnalyzer.CSharp" />
</ItemGroup>
```

Combine this with:

```xml
<Project>
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest</AnalysisLevel>
    <AnalysisMode>All</AnalysisMode>
    <CodeAnalysisTreatWarningsAsErrors>true</CodeAnalysisTreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  </PropertyGroup>
</Project>
```

…and your build will fail on serious code quality issues.
This can be a great safety net.

But it can also be noisy at first.
If some rules don't fit your context, you can adjust or suppress them in `.editorconfig` by setting the rule severity to `none`.

## 5. Set Up Local Orchestration

For a consistent local environment across your team, you'll want container orchestration.

You have two main options:

**Option 1: Docker Compose**

Add **Docker Compose support** in Visual Studio.
It will scaffold a `docker-compose.yml` file where you can define services like:

```yaml
services:
  webapi:
    build: .
  postgres:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: password
```

This lets every developer spin up the same stack locally with one command.

**Option 2: .NET Aspire**

[**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development) takes orchestration a step further.
It provides [**service discovery**](how-dotnet-aspire-simplifies-service-discovery),
[**telemetry**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet), and streamlined configuration, all integrated with your .NET projects.
It's become a **personal favorite of mine**.

You can add a .NET project and a Postgres resource with a few lines of code:

```csharp
var postgres = builder.AddPostgres("demo-db");

builder.AddProject<WebApi>("webapi")
       .WithReference(postgres)
       .WaitFor(postgres);

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

Aspire still uses Docker under the hood but provides a richer developer experience.

Whether you pick Docker Compose or Aspire, the goal is the same: a repeatable, reliable local setup that works the same on every machine.

## 6. Automate Builds with CI

Finally, I set up a simple [**GitHub Actions**](how-to-build-ci-cd-pipeline-with-github-actions-and-dotnet) workflow to validate each commit.

Example `.github/workflows/build.yml`:

```yaml
name: Build

on:
  push:
    # Filter to only run on main branch
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v5
        with:
          dotnet-version: 10.0.x
      - run: dotnet restore
      - run: dotnet build --no-restore --configuration Release
      - run: dotnet test --no-build --configuration Release
```

This ensures your project always builds and passes tests, and it catches issues before they reach production.
If the CI build fails, you know something's wrong right away.

When it comes to testing, I highly recommend exploring:

- [**Architecture testing**](shift-left-with-architecture-testing-in-dotnet) to enforce architectural rules in your codebase
- [**Integration testing with Testcontainers**](testcontainers-integration-testing-using-docker-in-dotnet)
  to spin up real dependencies in Docker during tests (you can run this locally and in CI)

This will give you confidence that your code works as expected in an (as close as possible) production-like environment.

## Wrapping Up

That's a wrap.
Your **new .NET project** is now set up with:

- consistent code style
- centralized build and package management
- code quality enforcement
- reproducible local orchestration
- continuous integration

These small setup steps save countless hours down the road and keep your codebase clean, predictable, and ready to scale.

Once your project setup is solid, the next step is designing scalable boundaries.
In my [**Modular Monolith Architecture**](/modular-monolith-architecture) course, I show how to grow a .NET application without turning it into a tangled mess,
through clear module boundaries, messaging, and domain isolation.

If you're looking for a practical walkthrough of these steps, check out [**this video**](https://youtu.be/QRgtcbxJlo0).

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**dotUltimate**](https://www.jetbrains.com/dotnet/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dul_promo):
The complete developer toolkit to cover all your .NET and game development needs, supercharged with
[**JetBrains AI**](https://www.jetbrains.com/dotnet/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dul_promo).
Enjoy access to Rider, ReSharper for Visual Studio and Visual Studio Code, dotTrace, dotMemory, dotCover, dotPeek, JetBrains AI,
and more tools with a single subscription - no need for multiple licenses.
[**Download now**](https://www.jetbrains.com/dotnet/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dul_promo)

[**Rovo Dev in GA**](https://bit.ly/474NhDY): Meet Atlassian's context-aware AI agent for the entire SDLC.
From code gen and review to docs and maintenance,
[**Rovo Dev helps you automate, write, and accelerate**](https://bit.ly/474NhDY).
Use Rovo Dev in Jira, your IDE, your terminal, and source control (Bitbucket & GitHub) to stay in flow.
[**Explore Rovo Dev**](https://bit.ly/474NhDY).

</Sponsorships>

Have you ever wondered if you could host a tiny .NET API without running servers 24/7?
You can!

AWS Lambda lets you run code on-demand, and with the [Amazon.Lambda.AspNetCoreServer.Hosting](https://www.nuget.org/packages/Amazon.Lambda.AspNetCoreServer.Hosting) library,
you can plug an ASP.NET Core [Minimal APIs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) straight into [AWS Lambda](https://aws.amazon.com/lambda/).

In this article we'll set up a minimal API, deploy it, and discuss how it performs.

Don't worry if you're new to serverless, I'll keep everything simple enough to follow along.

## Getting Your Minimal APIs Lambda-Ready

Let's start with the basics. You need just three things to turn your Minimal API into a Lambda function.

First, create your API:

```bash
dotnet new webapi -n MyLambdaApi
cd MyLambdaApi
```

Second, add Amazon's hosting package:

```powershell
Install-Package Amazon.Lambda.AspNetCoreServer.Hosting
```

Third, add one line to your `Program.cs`:

```csharp {4}
var builder = WebApplication.CreateBuilder(args);

// This line does all the Lambda magic
builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);

var app = builder.Build();

app.MapGet("/", () => "Hello from Lambda!");

app.Run();
```

That's it.
Your API now runs both locally (for testing) and in Lambda (for production).
When you run locally, it uses [Kestrel](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel) like normal.
When you deploy the app to AWS, Lambda takes over.

## Ship It to AWS

You'll need the [Lambda tools](https://github.com/aws/aws-extensions-for-dotnet-cli) installed:

```bash
dotnet tool install -g Amazon.Lambda.Tools
```

Then deploy with one command:

```bash
dotnet lambda deploy-function
```

The tool asks you a few questions (like the function name, which IAM role to use).
Pick the defaults if you're just testing.
In a minute or two, your API is live with a URL like: `https://[abc123xyz].lambda-url.[region-name].on.aws/`.

From the AWS Management Console, you can find your function with its URL and all the other details.

<div class="bordered">
  <Image
    src="blogs/mnw_163/aws_console_lambda_function.png"
    width={1906}
    height={883}
  />
</div>

## Measuring Cold Starts

Here's where things become interesting (and problematic).
Lambda functions "go to sleep" when nobody uses them.
Waking them up takes time, this is the famous **"cold start" problem**.

I ran some simple tests with a basic Minimal API:

- First request (cold): 2,153 ms
- Second request (warm): 154 ms
- Third request (warm): 143 ms
- After 10 minutes idle (cold again): 2,074 ms

As you can see, the first request is slow due to the cold start.
Subsequent requests are much faster, around 150 ms.
After 10 minutes of inactivity, the function goes cold again, and the next request takes over 2 seconds.
There's an optimization feature called [SnapStart](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html) that can help reduce cold start times,
but it has its own tradeoffs and isn't always suitable for every application.

Another thing to note is that I'm in Europe, and my Lambda function is in the US East (N. Virginia) region.
This adds network latency, so your results may vary based on your location and the region you choose.

Even when warm, the latency is higher than a typical server-hosted API.
This may be acceptable for low-traffic or non-critical endpoints, but it's something to consider.

Let's move beyond a "Hello World" example to something more realistic.

## CRUD Operations Benchmark

To see how a simple API performs in the real world, I built a tiny CRUD app that creates a record, fetches it, updates it and then deletes it.
First I ran each operation once to see the raw latency.
Then I used a load-testing tool with 100 virtual users (VUs) to measure average latency under a bit more stress.

```csharp
// POST /products - Create new product
app.MapPost("/products", async (CreateProductRequest request, NpgsqlDataSource dataSource) =>
{
    const string sql =
        """
        INSERT INTO Products (Name, Description, Price, CreatedAt)
        VALUES (@Name, @Description, @Price, @CreatedAt)
        RETURNING Id, Name, Description, Price, CreatedAt
        """;

    await using var connection = await dataSource.OpenConnectionAsync();
    var product = await connection.QueryFirstAsync<Product>(sql, new
    {
        request.Name,
        request.Description,
        request.Price,
        CreatedAt = DateTime.UtcNow
    });

    return Results.Created(
        $"/products/{product.Id}",
        new ProductResponse(
            product.Id,
            product.Name,
            product.Description,
            product.Price,
            product.CreatedAt));
});
// Other endpoints omitted for brevity:
// - GET /products/{id} - Get product by ID
// - PUT /products/{id} - Update product
// - DELETE /products/{id} - Delete product
```

The application uses .NET 8, [Npgsql](https://www.npgsql.org/) and [Dapper](https://www.learndapper.com/)
to interact with a PostgreSQL database running on [Amazon RDS](https://aws.amazon.com/rds/).
You can find the source code for this example (and the previous one) in [this repository](https://github.com/m-jovanovic/minimal-apis-on-lambda).

Here are the results:

**Single-call latency**

```text
| Operation  | Latency (ms) | Notes                           |
| ---------- | ------------ | ------------------------------- |
| Create     |     537      | Cold start plus object creation |
| Read       |     134      | Simple GET of the new record    |
| Update     |     140      | Changing one property           |
| Delete     |     167      | Removing the record             |
```

The create call took half a second because it included a cold start and initialization overhead.
Once the function was warmed up, the other operations completed in under two hundred milliseconds.

**Load test with 100 virtual users**

During the load test, I simulated 100 clients hitting the API at once.
AWS automatically scaled the Lambda function to handle the traffic, and average latencies dropped because the functions were already warm.
Here are the averages:

- **CREATE avg**: 129 ms
- **READ avg**: 132 ms
- **UPDATE avg**: 152 ms
- **DELETE avg**: 144 ms

These numbers show that once your function is up and running, Lambda can respond quite quickly even when many users are making requests.
Of course, actual times will vary depending on what your API does and how it stores data.

Remember that each of these operations involves network calls to the database, which adds latency.
Overall, I don't find these numbers bad for a serverless setup.

## Summary

Hosting minimal APIs in AWS Lambda is **surprisingly straightforward**.
With one library and a single method call, your ASP.NET Core code can run "without servers".
You pay only for the compute you use.
Also, the AWS Lambda free tier includes one million free requests per month, which is great for testing and light usage.

However, there are tradeoffs.
Because of cold starts and the overhead of starting the .NET runtime, latency isn't as low as hosting on a dedicated server.
If your API is mission-critical or requires sub-100 ms responses at all times, you may need to look at provisioned concurrency, containers, or a traditional host.

Lambda shines for small, [**event-driven**](event-driven-architecture-in-dotnet-with-rabbitmq) or intermittent workloads that don't justify a full-time server.
But it's less suitable for latency-sensitive or heavy, long-running applications.
For occasional or low-traffic API endpoints, though, **Lambda** offers a **cost-effective** and **simple** option.

That's all for today.

See you next week.

---


Previous issues of The .NET Weekly