
<Sponsorships>

[**MongoDB's new Voyage 4 series**](https://fandf.co/3NbvbcW), a unified family of text embedding models featuring shared embedding spaces,
lets you mix and match models for documents and queries in the same pipeline for a flexible,
cost-effective embedding solution for local development (voyage-4-nano) and production (voyage-4-large).
Mix, match, and optimize: [**start building with Voyage 4 (First 200M tokens free)**](https://fandf.co/3NbvbcW)

Building the next big thing?
[**MongoDB for Startups**](https://fandf.co/49JEDwU) gives you the tools and support to accelerate your growth.
Jumpstart your development with MongoDB Atlas credits; build on a unified data platform that integrates document storage, vector search, and database scalability;
and leverage MongoDB's technical expertise to [**grow from idea to IPO**](https://fandf.co/49JEDwU).

</Sponsorships>

Distributed systems are great for scalability, but they introduce a whole new class of problems.
One of the hardest problems to solve is **cache invalidation**.

In .NET 9, [**Microsoft introduced `HybridCache`**](hybrid-cache-in-aspnetcore-new-caching-library) to simplify caching.
It's a fantastic library that combines the speed of in-memory caching (L1) with the durability of distributed caching (L2) like Redis.
It also handles "cache stampede" protection out of the box.

However, there is a catch.

When you run multiple instances of your application, `HybridCache` doesn't automatically synchronize the local L1 cache across all nodes.
If you update data on **Node A**, **Node B** will continue serving stale data from its in-memory cache until the entry expires.

While HybridCache is a massive step forward, the lack of a built-in backplane for invalidation is a known limitation.
In fact, there is an active discussion on the [dotnet/extensions GitHub repository](https://github.com/dotnet/extensions/issues/5517) tracking this exact feature request.
Until that ships, we have to roll our own solution.

In this week's newsletter, we'll explore:

- The distributed caching dilemma
- Why `HybridCache` doesn't solve this alone
- Using Redis Pub/Sub as a backplane
- Implementing real-time cache invalidation

Let's dive in.

## The Distributed Caching Dilemma

Let's imagine a typical production scenario.
You have an API running on multiple servers (or pods) behind a load balancer.

To improve performance, you introduce [**caching**](caching-in-aspnetcore-improving-application-performance).
You want the speed of local memory, so you use `HybridCache`.

Here is the failure scenario:

1. **User A** updates their profile on **Server 1**.
2. **Server 1** updates the database and clears its local cache.
3. **User A** (or User B) hits **Server 2**.
4. **Server 2** still holds the _old_ profile data in its local `HybridCache`.
5. The user sees outdated information, since the local cache hasn't been invalidated.

<Image
  src="blogs/mnw_177/hybridcache_out_of_sync_scenario.png"
  width={2007}
  height={1378}
  alt="A sequence diagram showing two servers with HybridCache out of sync after a user update."
/>

**Why Not Just Shorten the Cache Duration?**

A common "hack" to solve this is to simply reduce the L1 cache duration (TTL).
For example, setting the local cache to expire every 10 seconds.

While this reduces the window of inconsistency, it doesn't solve the problem.
It just masks it.

This approach introduces two new issues:

- **Increased Latency**: You are now forcing your application to reach out to the distributed L2 cache (Redis) or the database much more frequently.
- **Lost Efficiency**: The main benefit of L1 caching is avoiding network requests entirely.
  If you expire data too fast, you lose the performance gain for the majority of your traffic.

For things like user permissions, feature flags, or pricing, "mostly correct" is often not good enough. You need immediate consistency.

## The Solution: Redis Pub/Sub Backplane

To solve this, we need a **backplane**.
It's a communication channel that connects all our application nodes.

When a cache entry is removed or updated on one node, we publish a message to the backplane.
All other nodes subscribe to this channel and, upon receiving the message, remove the corresponding key from their local cache.

Redis is already a popular choice for the L2 cache, so it makes perfect sense to use its [**Pub/Sub feature**](simple-messaging-in-dotnet-with-redis-pubsub)
for this signaling mechanism.

It works like this:

1. **Publisher:** The node that modifies data publishes a `cache-invalidation` message with the cache key.
2. **Subscriber:** All nodes listen to this channel.
3. **Action:** When a message arrives, they call `HybridCache.RemoveAsync(key)`.

<Image
  src="blogs/mnw_177/cache_invalidation_message_fanout.png"
  width={1873}
  height={1354}
  alt="A sequence diagram showing cache invalidation messages being published and received by multiple servers."
/>

## Implementing the Solution

We will need the `StackExchange.Redis` library to handle the messaging.

Let's start by defining a simple service to handle the publishing.
This service will be responsible for notifying the rest of the system that a key has changed.

```csharp
public interface ICacheInvalidator
{
    Task InvalidateAsync(string key, CancellationToken cancellationToken = default);
}

public class RedisCacheInvalidator(
    IConnectionMultiplexer connectionMultiplexer,
    ILogger<RedisCacheInvalidator> logger)
    : ICacheInvalidator
{
    private const RedisChannel Channel = RedisChannel.Literal("cache-invalidation");

    public async Task InvalidateAsync(string key, CancellationToken cancellationToken = default)
    {
        var subscriber = connectionMultiplexer.GetSubscriber();

        await subscriber.PublishAsync(Channel, new RedisValue(key));

        logger.LogInformation("Published invalidation for key: {Key}", key);
    }
}
```

Now, whenever you update an entity in your Command Handler or Service, you just call `ICacheInvalidator.InvalidateAsync`.

```csharp {3,20}
public class UpdateUserProfileHandler(
    AppDbContext dbContext,
    ICacheInvalidator cacheInvalidator,
    ILogger<UpdateUserProfileHandler> logger)
{
    public async Task Handle(int userId, string newName, CancellationToken ct)
    {
        // 1. Update the database
        var user = await dbContext.Users.FindAsync([userId], ct);
        if (user is null)
        {
             return;
        }

        user.Name = newName;
        await dbContext.SaveChangesAsync(ct);

        // 2. Invalidate the cache (Distributed)
        var cacheKey = $"user:{userId}";
        await cacheInvalidator.InvalidateAsync(cacheKey, ct);

        logger.LogInformation("Updated user and invalidated cache for {UserId}", userId);
    }
}
```

### The Background Listener

Next, we need a [**background service**](running-background-tasks-in-asp-net-core) that runs on every node.
It will subscribe to the Redis channel and evict keys from the local `HybridCache`.

**A quick note on self-publishing**:
Because Redis Pub/Sub broadcasts to everyone subscribed, the node that published the invalidation will also receive the message.
In this implementation, we simply remove the key again.
It's redundant but harmless, and it keeps the code simple.

Note that we are injecting `HybridCache` directly into our background service.
An alternative is using `IMemoryCache`, since that is the L1 cache inside `HybridCache`.

```csharp
public class CacheInvalidationService(
    IConnectionMultiplexer connectionMultiplexer,
    HybridCache hybridCache,
    ILogger<CacheInvalidationService> logger)
    : BackgroundService
{
    private const RedisChannel Channel = RedisChannel.Literal("cache-invalidation");

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var subscriber = connectionMultiplexer.GetSubscriber();

        await subscriber.SubscribeAsync(Channel, (channel, value) =>
        {
            string key = value.ToString();

            logger.LogInformation("Invalidating local cache for: {Key}", key);

            // This removes the item from the local L1 cache
            var task = hybridCache.RemoveAsync(key, stoppingToken);

            if (!task.IsCompleted)
            {
                task.GetAwaiter().GetResult();
            }
        });
    }
}

```

### Wiring It All Together

Finally, we need to register these services in our DI container.

```csharp
builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
    ConnectionMultiplexer.Connect("<REDIS_CONNECTION_STRING>"));

// Register HybridCache (defaults generally work fine for L1)
builder.Services.AddHybridCache();

// Register our invalidation services
builder.Services.AddSingleton<ICacheInvalidator, RedisCacheInvalidator>();
builder.Services.AddHostedService<CacheInvalidationService>();

```

Now, when **Node A** calls `InvalidateAsync("user:123")`, Redis pushes that message to **Node B**, **Node C**, and so on.
They all trigger `hybridCache.RemoveAsync("user:123")`, ensuring the next request fetches fresh data from the source (or the shared L2).

## A Better Way: FusionCache

If building your own backplane feels like reinventing the wheel, you should look at [**FusionCache**](https://github.com/ZiggyCreatures/FusionCache).

FusionCache is a mature, battle-tested library that has solved this exact problem for years.
It has a built-in backplane feature that automatically handles the Pub/Sub messaging for you.

Even better, FusionCache recently added an implementation of the HybridCache abstract class.
This means you can swap it in without changing much of your existing code.

```csharp {3}
// Using FusionCache's implementation of HybridCache
builder.Services.AddFusionCache()
    .WithBackplane(
        new RedisBackplane(new RedisBackplaneOptions { Configuration = "<REDIS_CONNECTION_STRING>" }))
    .AsHybridCache();
```

## Summary

`HybridCache` is a powerful addition to the .NET ecosystem, effectively merging the benefits of `IMemoryCache` and `IDistributedCache`.
However, for multi-node setups requiring high consistency, you still need a mechanism to synchronize the local caches.

Redis Pub/Sub offers a lightweight, effective solution to this problem.

By implementing a simple "bus" for invalidation messages, you get the best of both worlds:
the extreme performance of local caching and the data consistency of a distributed system.

Good luck out there, and see you next week.

---



<Sponsorships>

[**Meet your AI App and Agent Factory**](https://fandf.co/49R20Ur)\
It's never been easier to build, optimize, and govern AI apps and agents that understand your business context and deliver business impact.
Microsoft Foundry helps teams accelerate innovation with open-source frameworks, the widest model selection on any cloud, RAG on data stored anywhere,
secure MCP tools, and VS Code integration.
Govern the entire AI lifecycle with end-to-end observability, evaluations, and security controls.
Stop wrestling with disconnected AI tools.
Find out why Microsoft Foundry is used by developers at more than 80,000 organizations, including 80% of Fortune 500 companies.
👉 [**Get started in minutes**](https://fandf.co/49R20Ur)

Code your personal credit card to meet your needs.
With [**Klutch**](https://fandf.co/3NxWqhS), your card becomes an API-powered dev environment, offering direct access to financial data, unlimited virtual cards,
and full programmatic control over spending rules, automations, and real-time transaction behavior.
[**Check out what you can do with a Klutchcard**](https://fandf.co/3NxWqhS).

</Sponsorships>

Most systems don't need _global_ message ordering.

They need something simpler and more useful: **events must be handled in order per aggregate**.

Per `OrderId`, per `InvoiceId`, per `CustomerId`, or whatever your aggregate boundary is.
You can make this as broad or as narrow as you need.

This starts as an eventing problem, but if you follow the requirements to their logical conclusion, you'll end up with a workflow.
And that workflow has a name: **a saga**.

## Domain Events Feel Like the Clean Solution

[**Domain events**](how-to-use-domain-events-to-build-loosely-coupled-systems) are attractive because they come from first principles:

- An aggregate changes state
- It emits events describing what happened
- Handlers react and do useful work

You also get a nice mental model:

> State change → Event → Reaction

A typical example:

- `OrderPlaced`
- `PaymentCaptured`
- `OrderShipped`

But there's a catch.

Domain events are **brittle** when you try to use them for integration.

<Image
  src="blogs/mnw_176/domain_events_flow.png"
  width={2158}
  height={1056}
  alt="A sequence diagram showing an Aggregate committing a change, emitting Domain Events, which are then processed by multiple Event Handlers."
/>

If you publish directly from your transaction, you're coupling business correctness to an unreliable side effect:

- The transaction succeeds but publishing fails
- Publishing succeeds but the transaction rolls back
- Consumers process duplicates
- Retries cause reordering

So we keep the model, but harden the delivery.

## The Outbox Makes Publishing Reliable (but not ordered)

With an [**Outbox**](implementing-the-outbox-pattern), we store outgoing events in the same transaction as the aggregate update.

Then a background publisher reads the Outbox and pushes events to a queue.

This fixes the reliability problem:

- If the transaction commits, the event is persisted
- If the publisher crashes, it can resume later
- We can retry safely

<Image
  src="blogs/mnw_176/outbox_flow.png"
  width={3473}
  height={549}
  alt="A diagram showing an Aggregate committing a change along with an Outbox entry, which is then published to a Queue by a background process."
/>

Now we've made event publishing reliable.

But we haven't made event handling ordered.

## Competing consumers Are Great, Until Order Matters

The moment events hit a queue, we usually scale with the simplest lever: [**competing consumers**](event-driven-architecture-in-dotnet-with-rabbitmq).

Multiple instances consume from the same queue to increase throughput.

That works… until ordering matters.

Two events for the same `OrderId` can be processed at the same time:

- Consumer A receives `PaymentCaptured`
- Consumer B receives `OrderPlaced`
- Side effects run out of order

Even if the events were published in order, retries and redelivery can scramble processing order.

And now you have a subtle bug that only appears under load.

<Image
  src="blogs/mnw_176/competing_consumers.png"
  width={2093}
  height={1050}
  alt="A sequence diagram showing multiple consumers processing messages from a Queue concurrently, leading to out-of-order handling of events for the same aggregate ID."
/>

That's the key realization: queues scale work.
They don't preserve your invariants.

## What We Really Want is Per-Aggregate Ordering

You don't need one ordered line for _everything_.

You need many independent ordered lines, one per aggregate.

That usually holds true because:

- Aggregates already define consistency boundaries
- Events are naturally produced in order (v1, v2, v3…)
- The "correct" order is the aggregate's own timeline

If we could guarantee that **only one handler processes events for a given aggregate at a time**, most of the problem disappears.

The most direct solution is also the simplest: **use a single consumer for the whole stream.**

That enforces ordering, assuming events are published in order.

<Image
  src="blogs/mnw_176/single_consumer.png"
  width={1730}
  height={952}
  alt="A sequence diagram showing a single consumer processing messages from a Queue, leading to ordered handling of events for the same aggregate ID."
/>

But it has an obvious drawback.

## A Single Consumer Solves Ordering But Limits Scale

One consumer means:

- Throughput ceiling (one worker)
- Latency spikes under load
- Scaling becomes vertical, not horizontal

Even if your events are lightweight, you're artificially bottlenecking the system.

So we want:

- **Per-aggregate ordering**
- **Horizontal scaling**
- **Reliability (Outbox still stays)**

This is where teams often "invent" the next step.

## Publish the Next Message From the Handler

If competing consumers break ordering, one natural idea is:

> Don't let the queue decide what's next, we decide.

Instead of dumping all events into the queue and letting consumers race, we move to a chained approach:

1. Handle one message for an aggregate
2. When done, publish the **next** message to be handled

Now, the system processes a single message at a time per aggregate.

<Image
  src="blogs/mnw_176/choreographed_saga.png"
  width={2842}
  height={920}
  alt="A diagram showing a sequence of events being processed one at a time per aggregate ID, with each event handler publishing the next event upon completion."
/>

This is the key moment:

You've stopped building "event handlers".

You've started building a **workflow**.

And that workflow is… a saga.

## Congratulations, You Built a Choreographed Saga

A [**choreographed saga**](orchestration-vs-choreography) is a workflow where:

- Each step reacts to an event
- Performs work
- Emits the next event to trigger the next step

There isn't a single central coordinator.

Instead, we have a chain of events: "when X happens, do Y, then publish Z".

This pattern naturally fits your new requirement:

- Per-aggregate ordering is preserved (the chain is sequential)
- You can scale across aggregates (many chains in flight)
- Each step is isolated and retryable

It also forces a useful discipline:

- "What's the next step?" becomes explicit
- Boundaries between steps become clearer
- You can observe the workflow as a sequence

But choreography has a limitation: **control is distributed**, so tracking progress and handling exceptions can get messy.

So we take the final step.

## If You Want Control, Introduce a State Machine Saga

When the workflow becomes important, you often want:

- A single place that knows the current state
- Visibility into progress ("where are we stuck?")
- Explicit timeouts and retries
- Compensating actions when something fails

That's when you move from choreography to **orchestration** via a [**state machine saga**](implementing-the-saga-pattern-with-masstransit):

- The saga holds the workflow state
- Events drive transitions
- The saga decides what message to publish next
- You gain control and observability

<Image
  src="blogs/mnw_176/state_machine.png"
  width={2901}
  height={2171}
  alt="A state machine diagram showing states and transitions for a saga managing ordered message processing per aggregate ID."
/>

This doesn't replace the Outbox, by the way.

You still want reliable publishing.

You've just made the workflow explicit.

## Broker Support Helps with Ordering, not Correctness

It's worth calling out that you don't always have to build this yourself.

Many popular message brokers provide technical primitives for **ordered processing per key** (your aggregate ID):

- [Amazon SQS FIFO message groups](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/using-messagegroupid-property.html) (per key)
- [Azure Service Bus sessions](https://learn.microsoft.com/en-us/azure/service-bus-messaging/message-sessions) (per key)
- [Kafka Partitions](https://developer.confluent.io/courses/apache-kafka/partitions/) in a log (key → partition → ordered stream)
- [RabbitMQ "single active consumer"](https://www.rabbitmq.com/docs/consumers?#single-active-consumer) style semantics (per queue)

These features can eliminate the most common failure mode of competing consumers: **concurrent handling of messages for the same aggregate**.

But even with perfect per-aggregate ordering, you still need patterns around it to keep the system correct:

- **Outbox** to publish reliably (ordering is useless if events are lost)
- [**Idempotent consumers**](idempotent-consumer-handling-duplicate-messages) / **Inbox** because retries and duplicates still happen
- **Consistency boundaries** (what's safe to do inside the transaction vs outside)
- **Timeouts** + **compensation** when the "ordered sequence" is actually a business workflow that can partially fail

So broker-level ordering is a great foundation.
It reduces accidental complexity.
It just doesn't remove the need to model long-running work explicitly when the business demands it.

## Takeaway

If you follow the problem from first principles:

- Aggregates define the boundary where ordering matters
- The Outbox makes event publishing reliable
- Competing consumers break per-aggregate order
- A single consumer restores order but caps throughput
- Publishing "the next message" creates sequential progress per aggregate
- That sequential progress is a saga (choreographed first, state machine when you need control)

So you didn't reinvent something by accident.

You discovered that "ordered handling per aggregate at scale" is not a queue feature.

It's a workflow. And sagas are how we model workflows in distributed systems.

Once you see it that way, you stop fighting queues for ordering guarantees.

You design the workflow the business actually needs.

Hope this was helpful!

---



<Sponsorships>

[**Fly.io**](https://fandf.co/4pPGJRw) runs .NET apps where they belong - at the edge, close to users - with low latency and global reach.
Package your .NET app, deploy with flyctl, and scale worldwide with no ops overhead.
[**Learn how to deploy .NET with Fly.io**](https://fandf.co/4pPGJRw)

Oracle's new [**Database 26ai**](https://fandf.co/491wd3X) lets you run vector search, JSON relational duality,
and AI workloads directly in the database, without moving data between systems.
If you care about simpler architectures and fewer integration points, it's worth exploring.
[**Free here**](https://fandf.co/491wd3X)

</Sponsorships>

There is a specific kind of restlessness that only developers understand.
It's a quiet, persistent itch.
A mental "background process" that runs while you're eating, showering, or trying to sleep.
I call it **the urge to build**.

Looking back at [my GitHub contribution graphs](https://github.com/m-jovanovic) from the last few years, I see more than just green squares.
I see a timeline of my own evolution.

I was **chasing that dream** many developers have: build a small product, ship it, get users, maybe turn it into a business.
Most of those ideas didn't become a successful SaaS.

But that wasn't the point.

The point was that I was building constantly.
Learning constantly.
Shipping constantly.

And I loved it.

## The Indie Hacker Dream

Back in 2020, my contribution graph shows the classic "burst" pattern.
I was chasing the indiehacker dream.
You know the one: build a SaaS, get to ramen profitability, escape the 9-to-5, tweet about your MRR milestones.
I consumed every bootstrapper podcast, every "I made $10K/month" blog post, every ProductHunt launch breakdown.

I was working on a project called [Expensely](https://github.com/m-jovanovic/expensely-server).
I spent late nights pouring myself into this "genius" idea: a budgeting app.

Nothing revolutionary.
The world didn't need another expense tracker.
But I needed to build it.

Looking back now, it was far from genius.
But at the time, I was convinced that this was _the one_.

<Image
  src="blogs/mnw_175/github_contributions_2020.png"
  width={1350}
  height={600}
  alt="A GitHub contribution graph from 2020 showing a burst of activity in the end of the year."
/>

In 2021, that momentum stayed steady for five months before life (or perhaps reality) intervened.
Those green squares represent the **fun periods**.
They represent the thrill of architecting an application, the satisfaction of a passing test suite,
and the hope that you're building something that might change your life.

<Image
  src="blogs/mnw_175/github_contributions_2021.png"
  width={1350}
  height={600}
  alt="A GitHub contribution graph from 2021 showing steady activity for the first five months and then a tapering off."
/>

Expensely never became a business.
Most side projects don't.
But here's what I've come to understand: the outcome wasn't the point.

Even though those projects didn't become the next big SaaS, they were the forge where my skills were sharpened.
You don't "waste" time building something that fails.
You only waste time when you don't build at all.
And I mean this both metaphorically and literally.
Humans are meant to create.
When we stop creating, we stagnate.

## What Building Actually Gives You

When you build something from scratch - when you own every decision from the database schema to the button colors - you learn differently.
There's no senior developer to ask.
No established patterns to follow.
Every problem is yours to solve.

You can use [Railway-Oriented Programming](https://fsharpforfunandprofit.com/rop/) if you want to, because who is going to stop you?

Jokes aside, **functional programming** is **very useful**. You should learn it.

<Image
  src="blogs/mnw_175/rop_sample_code.png"
  width={938}
  height={890}
  alt="A screenshot of sample code implementing Railway-Oriented Programming in C#."
/>

Through my side projects, I wrestled with authentication, background jobs, payment integrations, deployment pipelines.
I made mistakes and spent late nights fixing them.
I built features nobody asked for and skipped features everyone needed.

There is **one thing side projects can't teach you** (unless you get users): dealing with the **consequences of your decisions**.
When you build for yourself, the only person affected by your mistakes is you.
When you build for users, every bug, every outage, every poor design choice has real consequences.

By mid 2021, the project had wound down.
I was settling into a comfortable routine at my day job, working as a senior engineer at a big corporation.
There was no time left for side projects.

## The Unexpected Pivot

By 2022, something changed.
My contribution graph exploded to over 1,600 commits.
But the focus shifted.
I wasn't building a product anymore.
I was building something more meaningful.
The repositories shifted to my tech blog and [YouTube projects](https://www.youtube.com/@MilanJovanovicTech).

I had **discovered** content creation.

The urge to build hadn't disappeared.
I found a new outlet.
Instead of building products for users, I was building educational content for developers.
Instead of SaaS metrics, I was tracking video views and newsletter subscribers.
To me it was something new, something exciting.

<Image
  src="blogs/mnw_175/github_contributions_2022.png"
  width={1350}
  height={600}
  alt="A GitHub contribution graph from 2022 showing steady activity throughout the year."
/>

I discovered that while I loved building software, I loved **explaining** it even more.
I transitioned from an aspiring founder to a software engineering educator.
At first it was just me writing and recording **things I wish someone had explained to me earlier**.

Then something interesting happened.

People started reading.
Watching.
Replying.
Asking questions.
More people showed up.
And then even more.

<Image
  src="blogs/mnw_175/youtube_milanjovanovictech.png"
  width={837}
  height={946}
  alt="A screenshot of the Milan Jovanovic Tech YouTube channel with over 140,000 subscribers."
/>

Today, I get to help thousands of developers around the world improve their careers.
It is, without a doubt, the **most rewarding work I've ever done**.

<div className="centered">
  <Image
    src="blogs/mnw_175/pca_testimonials.png"
    width={570}
    height={759}
    alt="A screenshot of testimonials from students of the Pragmatic Clean Architecture course."
  />
</div>

<figure className="figure-center">
  <Image
    src="blogs/mnw_175/pca_testimonials.png"
    width={570}
    height={759}
    alt="A screenshot of testimonials from students of the Pragmatic Clean Architecture course."
  />
  <figcaption>
    Student testimonials from [**Pragmatic Clean
    Architecture**](/pragmatic-clean-architecture).
  </figcaption>
</figure>

This is genuinely fulfilling work.
When someone messages me saying my content helped them land a job
or finally understand a concept they'd struggled with for years, that feeling is hard to describe.
I'm doing something meaningful.

And yet.

## The Lingering Itch

The urge to build something still remains.

It's not dissatisfaction.
It's not that content creation isn't "real" building, it absolutely is.
It's a different kind of building, certainly.
But this feeling I have is something more fundamental.
A part of my brain that wants to work on a fresh project.
That wants to solve a problem nobody has asked me to solve.
That wants to take an idea from nothing to something.

That's why I have a [Hetzner](https://www.hetzner.com/) server sitting idle right now.
Never know when I might need it.
Right?
Also, I'm getting a great deal for €3.29/month.
Can't argue with that.

<Image
  src="blogs/mnw_175/hetzner_server.png"
  width={1500}
  height={520}
  alt="A screenshot of a Hetzner server management dashboard showing a server."
/>

I think this urge never fully goes away for people like us.
We can channel it, redirect it, find new outlets for it.
But it's always there, lingering.
And maybe that's okay.
Maybe that restlessness is what makes us who we are.

## Why You Should Build Too

If you're reading this with your own idea rattling around in your head - some app concept, some tool you wish existed,
some problem you think you could solve - I want to tell you something.

**Build it.**

Not because it will make you rich.
Statistically, it won't.
Not because it will become the next big thing.
It probably won't be that either.

**Build it because the person who finishes that project will not be the same person who started it.**
You will learn things no tutorial can teach.
You will develop judgment that only comes from making real decisions with real consequences.
You will have stories, opinions, and experiences that set you apart.

The outcome is almost beside the point.
The transformation is the product.

Maybe you'll end up with a successful SaaS.
Maybe you'll end up with a failed project and a mass of hard-won knowledge.
Maybe, like me, you'll end up somewhere you never expected - doing work you couldn't have imagined when you wrote that first line of code.

You won't know until you build.

So open your terminal.
Type `git init`.
And start.

Let this be a year of building.

---



<Sponsorships>

Oracle's new [**Database 26ai**](https://fandf.co/491wd3X) lets you run vector search, JSON relational duality,
and AI workloads directly in the database, without moving data between systems.
If you care about simpler architectures and fewer integration points, it's worth exploring.
[**Free here**](https://fandf.co/491wd3X)

[**AI runs on data. Data runs on dbt.**](https://fandf.co/3MI0Tys)\
Give your data the structured context it needs for consistent, governed insights.
The new O'Reilly report, “Structured for Intelligence: Why AI Needs Governed, Discoverable and Provisioned Data,” is the essential roadmap.
Learn how to use dbt Labs and MCP to build safe, scalable AI driven analytics and confidently shift from dashboards to dialogue.\
[**Read the Full Report**](https://fandf.co/3MI0Tys)

</Sponsorships>

A couple of days ago, I was looking at a piece of code that's doing too much work.
I'm sure you'll be able to draw a parallel to something in your own applications.
Maybe it's a database call that should be faster, or an external API that's starting to bill you by the thousands.

My first instinct is: **"I'll just cache it"**.

In .NET, that usually means reaching for `IMemoryCache` or plugging in a distributed cache like Redis.

But have you ever stopped to wonder what's actually happening inside those libraries?\
Why do we need all that complexity just to store a value in memory?

So I spent the afternoon trying to build a [**high-performance cache**](caching-in-aspnetcore-improving-application-performance) from scratch.

I don't recommend DIY-ing your own caching library for production use.
But I learn best by doing something myself.
Understanding these patterns (concurrency, race conditions, and [**locking**](introduction-to-locking-and-concurrency-control-in-dotnet-6))
is what separates a "coder" from an engineer.

## The Starting Point

I was working on a simple currency conversion handler.
We're calling a third-party API to get exchange rates.
The API returns the current exchange rate for a given currency code (like EUR, GBP, JPY) against USD.

This is the initial implementation:

```csharp {23}
public static class CurrencyConversion
{
    public static async Task<IResult> Handle(
		string currencyCode,
		decimal amount,
		CurrencyApiClient currencyClient)
	{
		// Validate currency code format (3 uppercase letters)
		if (string.IsNullOrWhiteSpace(currencyCode) ||
			currencyCode.Length != 3 ||
			!currencyCode.All(char.IsLetter))
		{
			return Results.BadRequest(
				new { error = "Currency code must be a 3-letter uppercase code (e.g., EUR, GBP)" });
		}

		// Validate amount (must be positive)
		if (amount < 0)
		{
			return Results.BadRequest(new { error = "Amount must be a positive number" });
		}

		var rate = await currencyClient.GetExchangeRateAsync(currencyCode);

		if (rate == null)
		{
			return Results.NotFound(
				new { error = $"Exchange rate for {currencyCode} not found or API error occurred" });
		}

		var convertedAmount = amount * rate.Value;

		return Results.Ok(new ExchangeRateResponse(
			Currency: currencyCode,
			BaseCurrency: "USD",
			Rate: rate.Value,
			Amount: amount,
			ConvertedAmount: convertedAmount
        ));
    }
}
```

This works fine in your local dev environment.
But in production, if 100 people hit this at the same time, you're making 100 identical network calls.
Your API provider will hate you (and you may even get rate limited), and your latency will spike.

Now let's build a cache to fix this without using any external libraries.
Remember, we're doing this for learning purposes only.

## Level 1: Adding a `ConcurrentDictionary`

Your first thought is probably to store the rates in a `ConcurrentDictionary`. It’s thread-safe, so it feels like the right tool.

```csharp {4, 11}
private static readonly ConcurrentDictionary<string, decimal> Cache = new();

// In the Handler:
if (Cache.TryGetValue(currencyCode, out var cachedRate))
{
	return cachedRate;
}

var rate = await currencyClient.GetExchangeRateAsync(currencyCode);

Cache.TryAdd(currencyCode, rate.Value);
```

This definitely helps with performance under load.
Multiple threads can read and write to the dictionary without crashing.
But `ConcurrentDictionary` protects the _dictionary structure_, not your _logic_.

If 100 users request "EUR" at the exact same time, `TryGetValue` will return false for all of them.
They will all proceed to call the API.
This is a classic [**race condition**](solving-race-conditions-with-ef-core-optimistic-locking).
You've protected your memory, but you haven't protected the external API.

There's also another problem with this approach: the rates never expire.

## Level 2: Adding Cache Expiration

Currency rates don't stay the same forever.
We need a way to expire them.
Since `ConcurrentDictionary` doesn't have a "Time to Live" (TTL), we have to wrap our data.

```csharp {9,10}
// Store both the rate and the time it was created
private record CacheEntry(decimal Rate, DateTime CreatedAt);

// Our cache now stores CacheEntry objects
private static readonly ConcurrentDictionary<string, CacheEntry> Cache = new();
private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);

// Check: Is it there? And is it still "fresh"?
if (Cache.TryGetValue(currencyCode, out var entry) &&
    (DateTime.UtcNow - entry.CreatedAt) < CacheDuration)
{
	return entry.Rate;
}
```

Now we have expiration.
But we've actually created a new problem: [The Thundering Herd](https://en.wikipedia.org/wiki/Thundering_herd_problem) (a.k.a [Cache Stampede](https://en.wikipedia.org/wiki/Cache_stampede)).

Every 5 minutes, when the cache expires, all incoming traffic will see "stale" data and try to refresh it at once.

So we need to fix that next.

## Level 3: Solving the "Cache Stampede"

To fix the stampede, we need to ensure that only _one_ person can fetch the update while everyone else waits.

How do we do that in C#?

We use a `SemaphoreSlim` and a pattern called [Double-Checked Locking](https://en.wikipedia.org/wiki/Double-checked_locking).
We check the cache once (the "fast path"), then we lock, and then we check _again_ to see if someone else filled it while we were waiting for the lock.

```csharp {12,30,36}
// Basically a mutex but async-friendly
private static readonly SemaphoreSlim Lock = new(1, 1);

public static async Task<decimal> GetRateAsync(string code, CurrencyApiClient client)
{
	// Fast path: No locking needed
	if (Cache.TryGetValue(code, out var entry) && IsFresh(entry))
	{
		return entry.Rate;
	}

    var acquired = await Lock.WaitAsync(TimeSpan.FromSeconds(10)); // Avoid deadlocks
    if (!acquired)
    {
        throw new Exception("Could not acquire lock to fetch exchange rate.");
    }
	try
	{
		// Double-check: Did someone else finish the API call while we waited?
		if (Cache.TryGetValue(code, out entry) && IsFresh(entry))
		{
			return entry.Rate;
		}

		var rate = await client.GetExchangeRateAsync(code);
		var newEntry = new CacheEntry(rate.Value, DateTime.UtcNow);

		// Atomically update the cache
		// This is safe because we're inside the lock
		Cache.AddOrUpdate(code, newEntry, (_, _) => newEntry);
		return rate.Value;
	}
	finally
	{
		// Always release the lock
		Lock.Release();
	}
}
```

This is an improvement.
But something still feels off.

Can you spot the _problem_ with this code?

Our lock behaves like a global lock.
This means that if one thread is fetching "EUR", all other threads (even those requesting "JPY") are blocked until the "EUR" fetch completes.
This problem is called **lock contention**.

Let's fix that next.

## Level 4: Scaling with Keyed Locking

The "pro" move here is **Keyed Locking**.
We create a lock for every specific currency.
Since the number of currencies is finite, this isn't too memory-intensive.

We need an additional `ConcurrentDictionary` to hold our semaphores, per currency code.

```csharp {4}
private static readonly ConcurrentDictionary<string, SemaphoreSlim> Locks = new();

// In the Handler:
var semaphore = Locks.GetOrAdd(currencyCode, _ => new SemaphoreSlim(1, 1));
if (!Cache.TryGetValue(currencyCode, out var cachedRate) &&
	DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)
{
    var acquired = await semaphore.WaitAsync(TimeSpan.FromSeconds(10));
    if (!acquired)
    {
        throw new Exception("Could not acquire lock to fetch exchange rate.");
    }
	try
	{
		// Fetch and update logic...
	}
	finally { semaphore.Release(); }
}
```

The only thing that changes is how we acquire the lock.
Now, if one thread is fetching "EUR", other threads requesting "JPY" can proceed without waiting.
This is the most scalable version of our cache.

**But...** It only works in memory.
So it's not suitable for distributed systems or multiple server instances.
There are also a few more edge cases to consider, but you can explore those as an exercise.

## The Final Code

Here's the final version of our caching logic:

```csharp
public static class CurrencyConversion
{
    private record CacheEntry(decimal Rate, DateTime CreatedAt);
    private static readonly ConcurrentDictionary<string, CacheEntry> Cache = new();
    private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);

    private static readonly ConcurrentDictionary<string, SemaphoreSlim> Locks = new();

    public static async Task<IResult> Handle(
        string currencyCode,
        decimal amount,
        CurrencyApiClient currencyClient)
    {
        // Validate currency code format (3 uppercase letters)
        if (string.IsNullOrWhiteSpace(currencyCode) ||
            currencyCode.Length != 3 ||
            !currencyCode.All(char.IsLetter))
        {
            return Results.BadRequest(
                new { error = "Currency code must be a 3-letter uppercase code (e.g., EUR, GBP)" });
        }

        // Validate amount (must be positive)
        if (amount < 0)
        {
            return Results.BadRequest(new { error = "Amount must be a positive number" });
        }

        decimal? rate;
        var semaphore = Locks.GetOrAdd(currencyCode, _ => new SemaphoreSlim(1, 1));
        if (!Cache.TryGetValue(currencyCode, out var cachedRate) &&
            DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)
        {
            var acquired = await semaphore.WaitAsync(TimeSpan.FromSeconds(10));
            if (!acquired)
            {
                throw new Exception("Could not acquire lock to fetch exchange rate.");
            }

            try
            {
                // Double-check locking pattern: check again inside the lock
                if (!Cache.TryGetValue(currencyCode, out cachedRate) &&
                    DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)
                {
                    rate = await currencyClient.GetExchangeRateAsync(currencyCode);

                    if (rate == null)
                    {
                        return Results.NotFound(
                            new { error = $"Exchange rate for {currencyCode} not found or API error occurred" });
                    }

                    Cache.AddOrUpdate(currencyCode,
                        _ => new CacheEntry(rate.Value, DateTime.UtcNow),
                        (_, _) => new CacheEntry(rate.Value, DateTime.UtcNow));
                }
                else
                {
                    rate = cachedRate!.Rate;
                }
            }
            finally
            {
                semaphore.Release();
            }
        }
        else
        {
            rate = cachedRate!.Rate;
        }

        var convertedAmount = amount * rate.Value;

        return Results.Ok(new ExchangeRateResponse(
            Currency: currencyCode,
            BaseCurrency: "USD",
            Rate: rate.Value,
            Amount: amount,
            ConvertedAmount: convertedAmount
        ));
    }
}
```

The next step would be to extract the core caching logic into its own reusable class.
That way, you can use it in other parts of your application.

## Takeaway

Why go through all this trouble?

It's easy to look at a simple `ConcurrentDictionary` and think you're done.
But as we've seen, the gap between "it works" and "it scales" is filled with edge cases that can bring a production system to its knees.

When you use a library, it handles these edge cases for you.
But building it yourself teaches you about the "three pillars" of high-performance code:

1. **Thread safety**
2. **Lock contention**
3. **Resource protection**

Sometimes the most "boring" parts of our infrastructure, like a cache, are actually the most architecturally interesting.

There's also that 1% of the time when you need a custom solution that no library can provide.
So it's worth knowing the fundamentals of how these things work.

Modern libraries like [**HybridCache**](hybrid-cache-in-aspnetcore-new-caching-library) or
[FusionCache](https://github.com/ZiggyCreatures/FusionCache) handle this for you,
but understanding these patterns ensures you know exactly why your application behaves the way it does under load.

And since this is the last issue of the year, I wish you a fantastic New Year! 🎉

---



<Sponsorships>

[**Augment Code Review's**](https://fandf.co/48LADup) retrieval engine pulls the exact set of files and relationships
necessary for the model to reason about cross-file logic, API contracts, concurrency behavior, and subtle invariants,
putting Augment 10 pts above the competition on combined recall (55%) and precision (65%).
[**Check out Augment Code Review and catch real bugs without spamming your PRs**](https://fandf.co/48LADup)!

Use [**WorkOS Radar**](https://fandf.co/4s4pQnK) in your app for real-time **protection against bots, fraud, and free trial abuse**.
Radar uses device fingerprinting and advanced behavioral signals, like unknown devices, geo blocking,
and impossible travel to keep your customers safe!
[**Explore WorkOS Radar now**](https://fandf.co/4s4pQnK).

</Sponsorships>

**Real-time updates** are no longer a "nice-to-have" feature.
Most modern UI applications expect live data streams of some kind from the server.
For years, the go-to answer in the .NET ecosystem has been [**SignalR**](adding-real-time-functionality-to-dotnet-applications-with-signalr).
While SignalR is incredibly powerful, it's _nice to have_ other **options** for simpler use cases.

With the release of ASP.NET Core 10, we finally have a native, high-level API for **Server-Sent Events** (SSE).
It bridges the gap between basic HTTP polling and full-duplex WebSockets via SignalR.

## Why SSE Instead of SignalR?

[SignalR](https://dotnet.microsoft.com/en-us/apps/aspnet/signalr) is a powerhouse that handles
[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API), Long Polling, and
[SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) automatically, providing a full-duplex (**two-way**) communication channel.
However, it comes with a footprint: a specific protocol (Hubs), a required client-side library, and a need for "sticky sessions" or a backplane (like Redis) for scaling.

SSE is different because:

- **Unidirectional**: It's designed **specifically** for streaming data **from the server to the client**.
- **Native HTTP**: It's just a standard HTTP request with a `text/event-stream` content type. No custom protocols.
- **Automatic Reconnection**: Browsers natively handle reconnections via the **EventSource** API.
- **Lightweight**: No heavy client libraries or complex handshake logic.

## The Simplest Server-Sent Events Endpoint

The beauty of the .NET 10 SSE API is its simplicity.
You can use the new `Results.ServerSentEvents` to return a stream of events from any `IAsyncEnumerable<T>`.
Because `IAsyncEnumerable` represents a stream of data that can arrive over time,
the server knows to keep the HTTP connection open rather than closing it after the first "chunk" of data.

Here's a minimal example of an SSE endpoint that streams order placements in real-time:

```csharp
app.MapGet("orders/realtime", (
	ChannelReader<OrderPlacement> channelReader,
	CancellationToken cancellationToken) =>
{
	// 1. ReadAllAsync returns an IAsyncEnumerable
	// 2. Results.ServerSentEvents tells the browser: "Keep this connection open"
	// 3. New data is pushed to the client as soon as it enters the channel
	return Results.ServerSentEvents(
        channelReader.ReadAllAsync(cancellationToken),
        eventType: "orders");
});
```

When a client hits this endpoint:

1. The server sends a `Content-Type: text/event-stream` header.
2. The connection stays active and idle while waiting for data.
3. As soon as your application pushes an order into the `Channel`, the `IAsyncEnumerable` yields that item,
   and .NET immediately flushes it down the open HTTP pipe to the browser.

It's an incredibly efficient way to handle "push" notifications without the overhead of a stateful protocol.

I'm using a [**`Channel`**](lightweight-in-memory-message-bus-using-dotnet-channels) here as a means to an end.
In a real application, you might have a [**background service**](scheduling-background-jobs-with-quartz-net)
that listens to a message queue (like RabbitMQ or Azure Service Bus)
or a database change feed, and pushes new events into the channel for connected clients to consume.

## Handling Missed Events

The simple endpoint we just built is great, but it has one weakness: it's missing resilience.

One of the biggest challenges with real-time streams is connection drops.
By the time the browser automatically reconnects, several events might have already been sent and lost.
To solve this, SSE has a built-in mechanism: the `Last-Event-ID` **header**.
When a browser reconnects, it sends this ID back to the server.

In .NET 10, we can use the [`SseItem<T>`](https://learn.microsoft.com/en-us/dotnet/api/system.net.serversentevents.sseitem-1?view=net-10.0)
type to wrap our data with metadata like IDs and retry intervals.

By combining a simple in-memory **OrderEventBuffer** with the **Last-Event-ID** provided by the browser, we can "replay" missed messages upon reconnection:

```csharp {4,10,12}
app.MapGet("orders/realtime/with-replays", (
	ChannelReader<OrderPlacement> channelReader,
	OrderEventBuffer eventBuffer,
	[FromHeader(Name = "Last-Event-ID")] string? lastEventId,
	CancellationToken cancellationToken) =>
{
	async IAsyncEnumerable<SseItem<OrderPlacement>> StreamEvents()
	{
		// 1. Replay missed events from the buffer
		if (!string.IsNullOrWhiteSpace(lastEventId))
		{
			var missedEvents = eventBuffer.GetEventsAfter(lastEventId);
			foreach (var missedEvent in missedEvents)
			{
				yield return missedEvent;
			}
		}

		// 2. Stream new events as they arrive in the Channel
		await foreach (var order in channelReader.ReadAllAsync(cancellationToken))
		{
			var sseItem = eventBuffer.Add(order); // Buffer assigns a unique ID
			yield return sseItem;
		}
	}

	return TypedResults.ServerSentEvents(StreamEvents(), "orders");
});
```

## Filtering Server-Sent Events by User

Server-Sent Events is built on top of standard HTTP.
Because it is a standard `GET` request, your existing infrastructure "just works":

- **Security**: You can pass a standard JWT in the `Authorization` header.
- [**User Context**](getting-the-current-user-in-clean-architecture): You can access `HttpContext.User` to extract a User ID and filter the stream.
  You only send a user the data that belongs to them.

Here's an example of an SSE endpoint that streams only the orders for the authenticated user:

```csharp {3}
app.MapGet("orders/realtime", (
	ChannelReader<OrderPlacement> channelReader,
	IUserContext userContext, // Injected context containing user metadata
	CancellationToken cancellationToken) =>
{
	// The UserId is extracted from the JWT access token by the IUserContext
	var currentUserId = userContext.UserId;

	async IAsyncEnumerable<OrderPlacement> GetUserOrders()
	{
		await foreach (var order in channelReader.ReadAllAsync(cancellationToken))
		{
			// We only yield data that belongs to the authenticated user
			if (order.CustomerId == currentUserId)
			{
				yield return order;
			}
		}
	}

	return Results.ServerSentEvents(GetUserOrders(), "orders");
})
.RequireAuthorization(); // Standard ASP.NET Core Authorization
```

Note that when you write a message to a `Channel` it's broadcast to **all** connected clients.
This isn't ideal for per-user streams.
You'll probably want to use something more robust for production.

## Consuming Server-Sent Events in JavaScript

On the client side, you don't need to install a single npm package.
The browser's native `EventSource` API handles the heavy lifting, including the "reconnect and send Last-Event-ID" logic we discussed above.

```javascript
const eventSource = new EventSource('/orders/realtime/with-replays');

// Listen for the specific 'orders' event type we defined in C#
eventSource.addEventListener('orders', (event) => {
  const payload = JSON.parse(event.data);
  console.log(`New Order ${event.lastEventId}:`, payload.data);
});

// Do something when the connection opens
eventSource.onopen = () => {
  console.log('Connection opened');
};

// Handle generic messages (if any)
eventSource.onmessage = (event) => {
  console.log('Received message:', event);
};

// Handle errors and reconnections
eventSource.onerror = () => {
  if (eventSource.readyState === EventSource.CONNECTING) {
    console.log('Reconnecting...');
  }
};
```

## Summary

SSE in .NET 10 is the perfect middle ground for simple, one-way updates like dashboards, notification bells, and progress bars.
It's lightweight, HTTP-native, and easy to secure using your existing middleware.

However, **SignalR** remains the robust, battle-tested choice for complex bi-directional communication or massive scale requiring a backplane.

The goal isn't to replace SignalR, but to give you a simpler tool for simpler jobs.
Choose the lightest tool that solves your problem.

That's all for today. Hope this was helpful.

---



<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.

---


Previous issues of The .NET Weekly