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

---



<Sponsorships>

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

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

</Sponsorships>

Distributed systems are unreliable by nature.

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

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

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

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

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

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

## What Can Go Wrong When Publishing

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

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

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

Now imagine:

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

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

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

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

- Broker redeliveries
- Consumer failures + retries

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

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

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

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

For example, when publishing a NoteCreated event:

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

await publisher.PublishAsync(message);

```

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

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

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

That's where the idempotent consumer pattern comes in.

## Implementing an Idempotent Consumer in .NET

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

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

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

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

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

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

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

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

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

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

**1. The Idempotency Key**

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

You use:

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

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

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

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

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

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

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

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

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

Why this matters:

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

This is the core of idempotency:

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

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

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

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

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

No duplicate side effects.

This works, except for one caveat...

## Deterministic vs Non-Deterministic Handlers

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

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

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

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

There are two main strategies to deal with this.

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

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

For example:

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

```

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

**2. Store the Intent Locally**

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

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

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

## When Idempotent Consumer Isn't Needed

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

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

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

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

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

## Takeaway

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

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

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

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

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

Hope this was helpful.

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

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

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

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

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

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

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

### Query syntax

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

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

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

### Method syntax

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

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

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

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

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

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

The generated SQL is identical to the previous example.

Why this is better:

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

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

## Also New: `RightJoin`

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

Conceptually:

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

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

Here's the generated SQL:

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

## Wrapping Up

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

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

A few quick tips when writing LINQ queries:

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

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

See you next Saturday.

---


Previous issues of The .NET Weekly