DEV Community: dotnet

How a .NET dev built an AI assistant

Tran Manh Hung — Fri, 26 Jun 2026 19:26:28 +0000

Did you just get the task to “make an AI assistant” — and you mainly do .NET? Same. I’m also one of those people who rolls their eyes at a lot of the AI hype, and the internet is full of articles where every confident tutorial contradicts the previous one.

So instead of publishing one more “definitive guide” that will age badly in two weeks, here’s the version I wish I’d found: what my team actually decided to build, the wrong turns we took on the way, and the code that finally made it click — written for people who know C# but have never built an AI feature.

This is not a best-practices sermon. It’s more like: here’s the problem, here’s what we nearly built, here’s what annoyed me, and here’s what we landed on.

The feature

I work on an app that helps kids learn through interactive 3D models — a heart, a cell, a volcano — in the browser, AR, and VR. We’re adding Cori, an assistant you can talk to about whatever model is currently on screen.

“Rotate the heart left.” → it rotates

“Why is this chamber bigger?” → it explains

That means Cori has to talk and act at the same time, and both of those outputs have to reach a live 3D viewer.

That, for me, is the actual problem. Not “which model is smartest?” Not “which SDK has the coolest demo?” The interesting part is how the output gets to the client.

Because once you stop thinking about the model as the product and start thinking about delivery as the problem, the architectural decisions get a lot clearer.

Our stack, for context: the backend is .NET with Wolverine + Marten on PostgreSQL and the frontend is Svelte. Fair warning: this is not exactly the most well-paved road in AI land. A lot of AI tooling assumes Python or TypeScript first, and .NET support often arrives later, half-finished, or not at all. So if you’re on a similar stack, you’re probably not picking from polished examples — you’re cutting the path by hand.

30-second AI glossary

Before the story, here are the four words every AI article uses as if everybody was born knowing them.

LLM — the brain. Think of it like a function: text in, text out. On its own, it does nothing useful.
Tokens — the model does not hand you the full answer in one blob. It sends it in tiny chunks. Stream those chunks and the answer types itself instead of appearing after a suspicious silence.
Tools / function calling — you give the model a set of your own functions, like Rotate or SearchContent. Mid-response, it can ask for one of those functions to be called. It does not run your C# code itself — it asks, and your code executes it.
Agent — an LLM bundled with tools, memory, and instructions so it can be reused. In Microsoft Agent Framework, that’s the AIAgent type.

That’s the whole glossary. Enough vocabulary to survive the rest of the article without having to alt-tab every two minutes.

Part 0: I refused to get vendor-locked

The first decision had nothing to do with streaming or transport. It came from plain distrust.

My biggest fear was not “will the model be smart enough?” It was tying the whole codebase to one vendor SDK, one framework, one opinionated stack, and then getting stranded the moment the ecosystem changed direction — which, in AI, it absolutely will.

So the first rule became simple: talk to abstractions. Use generic interfaces in application code, and keep the actual provider — OpenAI, Deepgram, whoever wins this month — behind DI where it belongs.

Pleasant surprise: .NET actually gives you this now. Microsoft.Extensions.AI is basically the ILogger pattern, but for AI:

IChatClient — provider-neutral chat / LLM access
IEmbeddingGenerator — embeddings for vector or semantic search
ITextToSpeechClient — text-to-speech
Microsoft.Extensions.VectorData — vendor-neutral vector store abstractions

That means the provider stays a registration detail:

// Register once: OpenAI hidden behind the generic IChatClient.
builder.Services.AddKeyedSingleton<IChatClient>("CoriAI", (sp, _) =>
    sp.GetRequiredService<OpenAIClient>()
      .GetChatClient("gpt-4o-mini")
      .AsIChatClient()
      .AsBuilder()
      .UseFunctionInvocation()
      .Build());

And consuming it is boring in exactly the right way:

public sealed class Summarizer([FromKeyedServices("CoriAI")] IChatClient chat)
{
    public async Task<string> OneLiner(string topic, CancellationToken ct)
    {
        var reply = await chat.GetResponseAsync(
            $"Explain {topic} in one sentence.",
            cancellationToken: ct);

        return reply.Text;
    }
}

Nothing in that class knows or cares whether OpenAI is behind it. That is the point.

A small rant about Semantic Kernel

Full honesty: when we built the first version of Cori, we did not follow the neat abstraction rule I just described. We wired the code straight to Semantic Kernel, using its types directly and leaning on a bunch of APIs politely labeled [Experimental].

Then Microsoft merged the world around it, Microsoft Agent Framework showed up, Semantic Kernel stopped looking like the future, and the framework we had invested time into became “the old path” while we were still building.

Which meant we had to rewrite more code than I would like to admit.

That experience is exactly why I’m now stubborn about the abstraction layer. Part 0 is not hindsight wisdom from a calm architect on a mountain. It’s the bruise talking.

The new pipeline is built on Microsoft.Extensions.AI specifically because the next time Microsoft changes direction — and there is always a next time — I want that change to be a DI swap, not a weekend of find in files and quiet swearing.

Part 1: “just use SignalR for everything”

Once the “brain” side was sorted, the real question became transport: how do the AI’s words and actions actually reach the client?

Cori produces two very different kinds of output:

semantic output — text, tool calls, state
audio output — microphone data up, synthesized voice down

And at that point, every .NET developer has the same reflex: we already have a real-time transport, just use SignalR for all of it.

On paper, it looked perfect. One connection. One typed client. Browser and Unity both covered.

                ┌──────── ONE SignalR hub ────────┐
  client  ◄────►│  text + tool calls + state      │  ← semantic
                │  mic audio up / voice down      │  ← audio
                └──────────────────────────────────┘

Then we wrote down what that would actually mean building:

typed contracts for every event
token-by-token text streaming
tool-call lifecycle events like start → args → end
reconnect and session state sync
wiring backend events onto the hub cleanly

That is a surprising amount of custom transport code.

And none of that code is the product. It is just plumbing we invented for ourselves, in a format we would have to maintain forever.

That was the first important moment: we realized we were about to spend serious effort hand-building a private AI event protocol when maybe, just maybe, someone had already done that part for us.

Part 2: AG-UI does most of it for free

The reason we switched was the same instinct as before: I really did not want to own a custom message format for the next several years.

MAF ships with support for AG-UI, an open streaming protocol from the CopilotKit world. And annoyingly enough, it already defines almost the exact event shape we were preparing to invent by hand.

Turning the agent into a streaming endpoint is basically one line:

var agent = app.Services.GetRequiredKeyedService<AIAgent>("Cori");
app.MapAGUI("/cori", agent);

From the frontend side, it is just an HTTP POST and a streamed response:

const res = await fetch("/cori", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Rotate the heart left" }),
});

const reader = res.body!.getReader();
// decode each event/data line as it arrives

The response comes back as Server-Sent Events — a long-lived HTTP response that keeps writing labeled lines until the run is finished.

And the event stream is exactly the sort of thing we needed:

event: TEXT_MESSAGE_CONTENT   data: {"delta":"Sure, rotating "}
event: TEXT_MESSAGE_CONTENT   data: {"delta":"the heart now…"}
event: TOOL_CALL_START        data: {"name":"Rotate"}
event: TOOL_CALL_ARGS         data: {"direction":"LEFT","degrees":45}
event: TOOL_CALL_END          data: {}
event: RUN_FINISHED           data: {}

That is the whole magic trick.

The text types itself into the UI. Then the model decides to call Rotate. Then the 3D viewer reacts. Words and actions travel together on one stream, and the streaming protocol, event lifecycle, and session mechanics are not our responsibility anymore.

That was the first time the architecture started to feel sane.

The agent registration stays pleasantly small:

builder.Services.AddKeyedSingleton<AIAgent>("Cori", (sp, _) =>
    sp.GetRequiredKeyedService<IChatClient>("CoriAI")
      .AsAIAgent(new ChatClientAgentOptions
      {
          ChatOptions = new() { Instructions = CoriSystemPrompt.Base },
          Tools = [ /* Rotate, Zoom, SearchContent, ... */ ]
      }));

And grounding it in our own curriculum is just a context provider:

public sealed class ContentSearchProvider(IHybridContentSearch search) : AIContextProvider
{
    public override async ValueTask<AIContext> ProvideAIContextAsync(
        InvokingContext context,
        CancellationToken ct)
    {
        var q = context.RequestMessages.LastOrDefault(m => m.Role == ChatRole.User)?.Text;
        var hits = await search.SearchAsync(q, topK: 3, ct);

        return new AIContext
        {
            Instructions = $"Use this curriculum if relevant:\n{Format(hits)}"
        };
    }
}

Then you attach it to the agent and MAF calls it before each turn:

.AsAIAgent(new ChatClientAgentOptions
{
    ChatOptions = new() { Instructions = CoriSystemPrompt.Base },
    AIContextProviders = [ new ContentSearchProvider(search) ],
})

That matters because it keeps Cori anchored in our own educational content instead of free-associating from half-remembered internet knowledge.

What about audio?

Here is the important catch: AG-UI only carries text and JSON. No binary audio.

At first that sounds like a limitation. In practice, it turned out to be the insight.

Because audio was always going to be its own problem anyway.

So the real choice was never “SignalR or AG-UI?” The real choice was:

do we hand-build the text channel on top of SignalR, or take AG-UI for free and solve audio separately — which we were going to have to do either way?

Once we phrased it like that, the argument mostly ended itself.

Part 3: split the planes

This was the actual architectural decision.

We never found one ready-made approach that gave us everything — text streaming, tool calls, state, audio, cross-platform friendliness, decent developer ergonomics — in one clean package.

So instead of forcing everything through one pipe, we split the problem into two planes.

        ┌──────── Browser / Unity VR client ────────┐
        │  AG-UI (POST + SSE)      Audio (WebSocket) │
        └──────┬──────────────────────────┬─────────┘
   text/tools/ │ POST turn / SSE reply     │ mic up / voice down
   state       ▼                           ▼
     ┌──────────────────────┐   ┌──────────────────────────┐
     │ MapAGUI("/cori",agent)│  │ Audio gateway (no agent) │
     │  AIAgent — TEXT ONLY  │◄─┤  speech→text, voice down │
     │  tools = 3D commands  │ transcript cancel on barge-in│
     └──────────────────────┘   └──────────────────────────┘

Text goes through AG-UI.
3D actions go through tool calls on that same stream.
Audio gets its own connection.
The agent stays audio-unaware: text in, text and tool calls out.

That last point mattered more than expected.

Because once the agent no longer cares whether the input came from typing, speech-to-text, browser chat, or VR, the same brain can serve all of them. The channel becomes an integration detail instead of something smeared through the entire design.

The downside

This is not a fairy-tale architecture with no cost.

Splitting the planes means coordinating two channels. Barge-in gets trickier. The Unity story for AG-UI still feels less proven than I’d like. And the .NET AG-UI host is preview enough that version pinning is not optional.

Still, the trade-off felt worth it.

Owning an open protocol is better than owning a private one. POST/SSE and WebSocket also pass more easily through school networks than anything that smells like WebRTC or UDP, which matters a lot more in education than flashy diagrams on conference slides.

Part 4: voice is still very much open

I’m not going to fake certainty here. The text side feels understandable now. Voice still does not.

Text is nice because it is turn-based and bounded. One request, one response. Voice is continuous, latency-sensitive, messy, and full of edge cases: users interrupting, classroom noise, weird pauses, headsets with personality disorders, and all the other things reality likes to contribute.

What we have right now is a shape, not a finished answer.

Audio transport = WebSocket / SignalR-style approach for audio only. For raw bytes, reconnect behavior, auth, and Unity compatibility, it still makes sense there.
The frontend drives the turn. Speech-to-text produces transcript, the frontend sends that transcript into the AG-UI text path, and text-to-speech sends audio back down its own channel.
The agent never sees raw audio. It stays text-only.

Conceptually, it looks like this:

mic ─► speech-to-text ─► transcript ─► FE ─► MapAGUI run ─► text + tool calls
                                        FE ─► audio channel ─► text-to-speech ─► voice down

Why not WebRTC?

Because “the technically correct real-time media stack” and “the thing that behaves on random school devices, Macs, standalone VR headsets, and mystery tablets” are not always the same thing.

WebRTC is great in the right environment. Our environment is not the right environment often enough.

So the pragmatic approach is simpler: capture raw PCM on the client and send it over a plain WebSocket. It costs more bandwidth, but it is easier to reason about, easier to debug, and much more predictable across devices.

Sometimes the fancy option is right. Sometimes the right option is the one a tired developer can actually support in a school deployment without becoming a part-time audio detective.

Latency: looks scary, currently fine

The obvious concern with this design is hop count:

speech becomes transcript
transcript goes through the frontend
frontend starts the AG-UI turn
response text comes back
frontend requests or receives voice playback

That sounds slow on paper.

But in practice, for turn-based conversation, the added delay measured under a second. That is not zero, but it is also not enough to make the interaction feel broken.

So we are deliberately not optimizing that path yet.

If seamless speech-to-speech becomes a hard requirement, that decision probably changes.

What is still unresolved

This is the honest backlog:

Barge-in across two channels — interrupting Cori means stopping text output and audio playback together.
Seamless mode — always-open mic with automatic stop detection and direct speech-to-speech handling.
Scaling the audio path — stateless text streaming is easier to scale than long-lived, stateful audio connections.

So no, this is not the satisfying part of the blog post where everything is solved and there is triumphant orchestral music in the background.

Voice is still where the dragons are.

What I’d tell past me

If I had to compress the whole thing into a few lessons, it would be these:

Abstract the vendor, not the hype. Microsoft.Extensions.AI outlives whatever framework is fashionable this quarter.
Look for the open protocol before inventing one. We nearly built by hand what AG-UI already gives us.
Find the real seam. “SignalR vs everything else” was the wrong question. “Text vs audio” was the useful one.
Keep the agent boring. Text in, text out, tool calls in the middle. The less channel-specific nonsense the agent knows, the more reusable it becomes.

That last point is probably my favorite. In AI work, there is always pressure to make the “brain” feel magical. Most of the time, the better move is to make it boring, predictable, and easy to swap around.

What this article is really about

On the surface, this post is about a .NET team building an assistant for a 3D learning product.

But underneath that, it is really about something more familiar: trying to add a new capability without letting the hype blow up the architecture.

The decisions we’ve landed on so far are these:

Vendor-neutral AI via Microsoft.Extensions.AI for chat, embeddings, and text-to-speech.
A single AIAgent exposed over AG-UI using MapAGUI.
Two transport planes — AG-UI for text and tool calls, a separate real-time channel for audio.
An audio-unaware agent so the same brain can serve browser, AR, VR, typed chat, and spoken interaction.

Each of those will probably become its own follow-up article because each one hid more detail than expected.

There is still a lot of implementation left. None of this is “battle-tested and perfect.” It is “this is the architecture we chose, this is why we chose it, and this is the shape of the problems we are still solving.”

Which, honestly, is probably more useful than another article pretending the road was smooth.

If you are a .NET developer trying to build your first AI feature, that is the main thing I would want to pass on: you do not need to start by finding the smartest model. You need to find the seam in your system, protect your abstractions, and avoid writing infrastructure you do not actually want to own.

Most .NET background job systems are wrong.

Oleksandr Viktor — Fri, 26 Jun 2026 18:33:36 +0000

Most .NET background job systems are wrong.

They look simple:

BackgroundJob.Enqueue(() => DoWork());

But what actually happens?

Job → retry → pipeline → continuation → retry → ???

At some point:
❌ you don’t know why it ran

❌ you don’t know what triggered next

❌ you can’t explain execution

This becomes a problem when background jobs are business logic.

So I built WJb.

Not a framework.
An explicit execution engine.

Where everything looks like this:

Job → Action → Next Job

And every step is defined in code:

return ActionResults.Next(
JobCommands.Next(...)
);

No magic.
No implicit pipelines.
No hidden retries.

You always know:
✅ why a job runs

✅ what happens next

✅ how the flow evolves

Try it in 30 seconds:
👉 https://github.com/UkrGuru/WJb.Demo/tree/main/quickstart

NuGet:
👉 https://www.nuget.org/packages/WJb/0.101.1

If this idea resonates — I’d love your feedback.

Back to Simplicity: Why We Built CALM, a Lock-Free Single-Thread Messaging Library for .NET

nullmake — Fri, 26 Jun 2026 18:30:55 +0000

Hello everyone! For many years, I have been developing equipment control software and long-term support products using .NET/C#. Based on the experiences gained through working with various development teams, I would like to talk about why I created CALM (Cooperative Async Lock-free Messaging), an open-source library for .NET.

The Magic of UI Thread + Event-Driven + async/await

My journey with .NET/C# began around the days of .NET Framework 4.0. At the time, code-behind in Windows Forms was incredibly intuitive. It allowed me to join the development team and become productive in a very short period.

Back then, executing time-consuming operations on a separate thread and returning the results to the UI thread via callbacks was painful and error-prone. However, the introduction of async/await in .NET Framework 4.5 completely shifted the paradigm. The SynchronizationContext magically handled thread marshaling behind the scenes, and our code became amazingly simple.

"Running asynchronous operations safely on a single thread (the UI thread) via an event-driven approach" — this seamless developer experience was my starting point.

Divide and Conquer, Dependency Management, and CQS

As our product evolved, the codebase grew, and the development team expanded beyond a certain size. Suddenly, the software became exponentially complex. Following industry best practices, we introduced MVP and MVVM patterns to separate the UI from the business logic. We also refactored our domain models based on Domain-Driven Design (DDD) and Clean Architecture principles, alignment with the team's domain knowledge.

While this helped organize the logic within individual models, it introduced a new nightmare: complex dependencies between models. We struggled heavily with initialization, especially with models that had circular or mutual dependencies.

To break this web of tight coupling, we introduced a mechanism that combined the Observer pattern (inspired by Android's EventBus) with the philosophy of CQS (Command Query Separation). By leveraging message-based, loosely coupled communication, we successfully eliminated direct dependencies.

The Trap of Multi-Threading and Race Conditions

However, as the system evolved, the backend model layer—now completely detached from the UI thread—transformed into a concurrent wild-west where numerous background threads crossed paths.

Writing concurrent code while keeping multi-threading issues in mind is incredibly delicate; even senior engineers frequently get flagged by static analysis tools. For junior engineers, it is an uphill battle to fully understand atomic operations or context switching, and constantly choose the right tool from the concurrency toolbox:

Heavy-handed synchronization via lock or SemaphoreSlim
Thread-safe collections like ConcurrentDictionary
Low-level optimizations with Interlocked or Volatile

"What we really need to focus on is not low-level concurrency control. It should be pure business logic."

Faced with this dilemma, the team made a radical decision: "Let's run the backend model layer on a dedicated, single-threaded event loop, just like the UI thread."

At the time, we drew inspiration from Unity's Coroutines. As long as developers understood the simple rule of using yield return instead of Thread.Sleep or Task.Delay, anyone could easily write safe logic without worrying about race conditions. Although there were limitations—such as not being able to use yield inside try/catch blocks or blocking other operations during heavy I/O—we could easily work around them, making it a perfectly acceptable trade-off.

8 Years Later: The Birth of CALM

Today, I work as a freelancer. Over the years, I found that the "single-threaded execution engine + CQS messaging" approach I built in the past was still highly effective for solving complexity in modern applications.

This realized potential led me to redesign the entire concept from scratch for modern .NET and release it as an open-source library called CALM.

https://github.com/nullmake/calm-dotnet

The core mission of CALM is to bring that nostalgic simplicity of "UI Thread + Event-Driven + async/await" directly into backend and equipment-control logic layers.

1. Unleashing Power with Native Tasks (`async/await`)

The biggest drawbacks of the old coroutine era—such as try/catch constraints and I/O blocking—have been completely solved by building the execution engine natively on top of C# Task (async/await).

2. Consistency via Outbox / Unit of Work

To make the CQS pattern more robust, CALM natively integrates the Unit of Work and Outbox patterns. Internal events published during a command handler's execution are deferred; they are only dispatched to the message queue once the command (the async method) completes successfully. This prevents state inconsistencies when unexpected errors occur halfway through an operation.

3. Guardrails via a Powerful Roslyn Analyzer (Boosting DX)

To get the most out of a single-threaded messaging loop, there is one absolute rule: Never unintentionally escape the engine thread. To save developers from the mental burden of tracking this, CALM comes bundled with a dedicated Roslyn Analyzer.

It instantly detects invalid handler signatures and warns you about accidental thread escapes caused by ConfigureAwait(false) right in your IDE or during build time.

4. Intentional Multi-Threading Offloading

You might wonder: "If everything runs on a single thread, won't heavy CPU-bound tasks block the entire system?" CALM solves this elegantly. For heavy operations that do not suffer from race conditions—such as re-archiving a ZIP file to reduce its size—CALM explicitly allows you to use .ConfigureAwait(false) to offload the work to the ThreadPool. This gives developers the flexibility to explicitly control concurrency while staying safely within the guardrails.

Conclusion

When creating this library, the hardest part was choosing the right name and description. Technically speaking, its role is:

CALM (Cooperative Async Lock-free Messaging)
A lock-free, single-thread messaging library for .NET.

However, what I truly wanted to solve with this library is a fundamental developer question: "How can we free ourselves from the fear of multi-threading and keep our code elegantly simple?"

It is not as generic as MediatR, nor as heavyweight as Akka.NET. It brings back that exact sense of security and ease we felt when writing events on the UI thread, applying it directly to complex backend state management.

I hope this story gives you some inspiration for your battle against software complexity. If you find the project interesting, please consider dropping a star or sharing your feedback!

GitHub: nullmake/calm-dotnet
Document: CALM Documentation
NuGet: Calm.Core

Thank you for reading until the end!

Building a Page Cache That Doesn't Count: Epoch-Based Memory Management

Loïc Baumann — Fri, 26 Jun 2026 15:23:52 +0000

💡Typhon is an embedded, persistent, ACID database engine written in .NET that speaks the native language of game servers and real-time simulations: entities, components, and systems.

It delivers full transactional safety with MVCC snapshot isolation at sub-microsecond latency, powered by cache-line-aware storage, zero-copy access, and configurable durability.

Series: A Database That Thinks Like a Game Engine

Why I'm Building a Database Engine in C#

What Game Engines Know About Data That Databases Forgot

Microsecond Latency in a Managed Language

Deadlock-Free by Construction

Three Durability Modes, One WAL

Building a Page Cache That Doesn't Count (this post)

MVCC at Microsecond Scale (coming soon)

GitHub repo • 📬 Subscribe via RSS

A transaction that reads a thousand pages should pay for reading a thousand pages. Mine used to pay for two thousand atomic operations on top — one to pin each page so the cache wouldn't yank it out from under a live pointer, one to unpin it afterward — before a single byte of useful work happened.

That bookkeeping was pure tax. Worse, it was contended tax. The page cache in Typhon today touches those same thousand pages and pays for exactly two operations, flat, regardless of the count. This post is about how the counter went away — and the one corner where I had to bring a smaller one back.

📍 Where we are

A quick recap for anyone joining mid-series. Typhon stores everything — components, indexes, the lot — in 8 KB pages. Those pages are cached in a single byte[] that is pinned with a GCHandle so the GC can never move it. Pinning is what makes the rest of the engine possible: once the backing array is fixed in memory, the hot paths hand out raw pointers and ref T interior references straight into the cache slot. No copy, no marshaling, no managed wrapper. A read of a component is a pointer add and a dereference.

That zero-copy guarantee is also the whole problem. The cache is finite — 256 pages by default — so when it fills, a clock-sweep eviction picks a victim slot and reuses it for a different file page. If a reader is still holding a ref Position into that slot when the sweep recycles it, the reader is now looking at someone else's data. A use-after-free, in a managed language, with no exception to tell you it happened — just a silently wrong number.

So the cache needs a lifetime rule: a slot must not be evicted while anyone still holds a pointer into it. The interesting part is not that rule. Every cache has it. The interesting part is what you pay to enforce it.

🧾 The obvious answer, and its bill

The textbook enforcement is reference counting. Every page carries a counter. You take a reference (++) before you read, you drop it (--) when you're done, and eviction skips any page whose count is above zero. Simple, correct, and the first thing I shipped — Typhon's early page cache had exactly this, a per-page ConcurrentSharedCounter.

It has three costs, and they compound:

It's 2N. A transaction that touches N pages does N increments and N decrements. The work scales with the data, which is the opposite of what you want from bookkeeping.
The decrement is mandatory and paired. Every acquire needs its matching release on every exit path, including exceptions. Miss one and the page is pinned forever — a slow leak that strands cache slots until the engine wedges. This is the half that generates bugs.
The counter is shared, mutable, cross-core state. That ++/-- is an Interlocked operation — an atomic read-modify-write. When two worker threads touch the same hot page — a B+Tree root, say — its counter's cache line ping-pongs between their cores. The atomic instruction isn't the expensive part; the coherency traffic is. A contended counter can cost an order of magnitude more than an uncontended one, and the hottest pages are exactly the ones every thread wants.
It clutters everything it touches. A mandatory paired release means scaffolding at every call site — hundreds of using blocks whose entire reason to exist is a Dispose that decrements a counter. And the moment that overhead shows up in a profile, you start bending the code to dodge it: paths that steal an already-held reference instead of taking a fresh one, so an increment here cancels a decrement there. Each of those tricks is correct only under assumptions the next reader can't see from the call site. The counter didn't just cost cycles — it spread through the codebase and made the whole engine harder to reason about. That cost is invisible in a microbenchmark and very visible six months later.

Reference counting answers a question the cache never actually asked: "exactly how many people are looking at this page right now?" Eviction doesn't need that number. It needs a cheaper, weaker fact: "is it safe to reclaim this slot yet?" Those are different questions, and the second one has a much cheaper answer.

⏱️ The reframe: stop counting, start timing

The technique is epoch-based reclamation (EBR) — the same family of idea behind RCU in the Linux kernel. Instead of tracking who holds what, you track time, coarsely, and you only reclaim memory once enough time has passed that nobody could still be holding the old version.

💡 The intuition. Think of a museum that wants to renovate a gallery — but only once every visitor who might still be wandering through it has gone home. The expensive way is to tag each visitor and constantly track which gallery they're standing in; that's reference counting. The cheap way: stamp every visitor at the entrance with the hour they arrived, and have each gallery note the last hour anyone walked through it. Now the renovation crew checks a single number — the arrival time of the earliest visitor still in the building. Any gallery whose last visit predates that time is guaranteed empty of anyone who could still be inside, so the crew can move in. No per-visitor ledger, just one question: who's the oldest person still here? Epoch-based reclamation is that museum — the visitor's arrival stamp is the epoch a thread pins on entry, the gallery's last-walked hour is the page's stamp, and "the earliest visitor still inside" is the threshold eviction compares against.

"Time" here is a single global counter — the epoch — that ticks forward. The protocol has three moves:

Enter. When a thread starts a unit of work, it publishes the current epoch into a slot of its own: "I am active, and I started at epoch E."
Stamp. Every page the thread touches gets tagged with the current epoch — fire-and-forget, no matching release.
Exit. When the thread finishes, it clears its slot and ticks the global epoch forward by one.

Eviction then asks one question of a page: is its stamp older than the oldest still-active thread? If every active thread started after this page was last touched, no one can be holding a pointer into it, and the slot is free to recycle. That comparison is the entire safety check.

The asymmetry is the whole win. The expensive, bug-prone, contended half of reference counting — the mandatory paired release on every page — disappears entirely. Releasing is now a single global tick that retires all of a transaction's pages at once. What's left on the acquire side is a stamp that is uncontended and usually a no-op.

⚙️ How it actually works

Three types carry the design (src/Typhon.Engine/Foundation/Concurrency/internals/):

EpochManager — one per engine. Owns the global epoch counter and the thread registry.
EpochGuard — a ref struct RAII scope. Enter on construction, advance the epoch on the outermost exit. Being a ref struct, it can't escape to the heap or get boxed; it has to live on the stack and be disposed.
EpochThreadRegistry — a fixed array of per-thread slots holding each thread's pinned epoch.

A transaction wraps its whole lifetime in one guard:

// Managed by Transaction — one scope per unit of work
using var guard = EpochGuard.Enter(epochManager);

// Every page access inside this scope is protected, no per-page bookkeeping
pmmf.RequestPageEpoch(filePageIndex, epochManager.GlobalEpoch, out int memPageIndex);
byte* addr = pmmf.GetMemPageAddress(memPageIndex);
// ... read/write through raw pointers, hold ref T across many pages ...

Entering publishes the epoch into the thread's own slot. The hot path is a single write to thread-local memory — no atomic, no contention:

// EpochThreadRegistry.PinCurrentThread — outermost scope pins, nesting is free
var depth = _slots[slot].Depth;
_slots[slot].Depth = depth + 1;
if (depth == 0)
    _slots[slot].PinnedEpoch = epoch;   // publish: "active, started at this epoch"
return depth;

Stamping a page is an atomic-max — never let a page's stamp go backward — that skips the atomic write entirely in the common case where the page is already current for this epoch:

// PagedMMF.RequestPageEpoch — tag the page, never moving the stamp backward
long existing;
do
{
    existing = pi.AccessEpoch;
    if (currentEpoch <= existing)
        break;                  // already protected this epoch — no write at all
} while (Interlocked.CompareExchange(ref pi.AccessEpoch, currentEpoch, existing) != existing);

That Interlocked.CompareExchange is a compare-and-swap (CAS): it stores the new epoch only if the field still holds the value we just read, so two threads stamping the same page can't clobber each other. The first touch of a page in an epoch does one such CAS; every subsequent touch breaks out at the currentEpoch <= existing guard — a plain read and a compare, no atomic at all. And — this is the point — there is no release. Nothing to pair, nothing to forget, nothing to run in a finally.

Exiting the outermost scope is where the single shared atomic lives — the global epoch tick:

// EpochManager.ExitScope — outermost exit retires the whole transaction's pages
internal void ExitScope(int expectedDepth)
{
    if (_registry.UnpinCurrentThread(expectedDepth))
    {
        var newEpoch = Interlocked.Increment(ref _globalEpoch);
        TyphonEvent.EmitConcurrencyEpochAdvance((uint)newEpoch);
    }
}

And eviction is the comparison the whole scheme exists to make cheap. MinActiveEpoch is the smallest epoch any thread is still pinned to; a page survives if its stamp is at least that:

// PagedMMF.TryAcquire — the eviction guard, minus the dirty/in-flight checks
if (info.AccessEpoch >= minActiveEpoch)
    return false;   // a transaction old enough to hold a pointer is still live — skip

Walk the invariant once and it clicks. A thread that pinned epoch E contributes E to MinActiveEpoch, so MinActiveEpoch ≤ E. Any page it stamped was stamped at the global epoch at access time, which is ≥ E. So while that thread is live, every page it ever touched satisfies AccessEpoch ≥ E ≥ MinActiveEpoch and cannot be evicted. The moment it exits — and no older thread remains — MinActiveEpoch climbs past those stamps and they all become reclaimable together. This is a grace period, exactly as in RCU: reclamation waits until every reader that could have seen the old state has gone away.

📊 The numbers

Measured with BenchmarkDotNet on a Ryzen 9 7950X (Zen 4), .NET 10, RELEASE:

Operation	Cost	Allocations
`EpochGuard` enter + exit (incl. global tick)	3.5 ns	0
Three-level nested enter/exit	8.8 ns	0
`MinActiveEpoch` (eviction check, no threads pinned)	0.8 ns	0
`MinActiveEpoch` while a thread is pinned	6.6 ns	0
Page-cache hit (`RequestPageEpoch`, slot resident)	6.5 ns	0

The number that matters is the first one: 3.5 ns for a transaction's entire eviction-protection obligation, and it does not move when the page count goes up. A transaction touching one page and a transaction touching ten thousand pay the same 3.5 ns of protection overhead. The per-page stamps on top are uncontended and frequently free; the contended, paired, O(N) release is gone.

Put that against the model it replaced: a thousand-page transaction was a thousand Interlocked increments and a thousand decrements, on a thousand separate counters, several of them hot enough to bounce across cores on every touch. Trading 2,000 contended atomics for one global tick is the kind of win you only get by answering an easier question.

⚖️ Trade-offs, and the one place pure epochs weren't enough

Epoch protection is conservative — that's the source of both its speed and its cost. It doesn't know which pages a transaction is done with; it only knows the transaction is still running. So a transaction pins every page it has ever touched for its entire lifetime, whether it still needs them or not.

For short transactions that's exactly right and basically free. For a long one it bites: if a single transaction's working set grows past the cache size, every page it has stamped is epoch-protected, so eviction has no legal victim. The cache can't make room, and AllocateMemoryPage runs into a backpressure wall and eventually times out. Reference counting wouldn't have this problem — it could evict a page the long transaction had touched and released. Epochs can't, because there is no "released" until the scope exits. That working-set-fits-in-cache constraint is a real, documented limit of the design, not a bug I haven't gotten to.

The mitigation is to let a long-lived thread refresh its epoch mid-flight — advance its own pin without unpinning — so pages it touched earlier age out and become evictable while it keeps running:

// EpochManager.RefreshScope — stay continuously pinned, but move forward in time
var newEpoch = Interlocked.Increment(ref _globalEpoch);
_registry.RefreshPinnedEpoch(newEpoch);   // no unpinned window; MinActiveEpoch never gaps

Which is where the pure model sprang a leak. The whole premise is that a page is safe as long as its epoch is live. But a caller can hold a raw ref T into a page across a refresh — and a refresh deliberately ages that page out, marking it evictable while the pointer is still on the stack. The coarse epoch clock can't see a pointer that outlives the epoch that created it.

So pure EBR wasn't quite enough, and I had to bring back a small, targeted counter: SlotRefCount. It tracks the much narrower fact of "a live accessor slot is pointing at this page right now," and it gates eviction alongside the epoch check. The full guard is the conjunction:

// Evict only when nobody can be looking — by epoch OR by raw pointer
(DirtyCounter == 0) && (AccessEpoch < MinActiveEpoch) && (SlotRefCount == 0)

It would be tidier to say I deleted reference counting outright. The honest version is that I moved it: epochs handle the common case — thousands of pages, retired in one tick — and a tiny refcount covers the narrow case epochs structurally can't see, the raw pointer that escapes its epoch. The 2N tax is gone from the hot path; what remains is a counter that almost never moves.

🧰 Two details worth stealing

Cache-line-pad the per-thread slots. The registry's whole reason to exist is that threads pin and unpin without fighting each other. Pack two threads' epoch fields into one cache line and you've reintroduced exactly the false-sharing the design set out to kill. Each slot is its own cache line:

// EpochThreadRegistry — one cache line per thread, no false sharing on pin/unpin
[StructLayout(LayoutKind.Explicit, Size = 64)]
internal struct PaddedEpochSlot
{
    [FieldOffset(0)]  public long PinnedEpoch;  // hot: written every enter/exit
    [FieldOffset(8)]  public int  Depth;        // hot: nesting depth
    [FieldOffset(12)] public int  SlotState;    // warm: CAS on claim/free
    // bytes 16–63: padding to fill the line
}

A pinned epoch is a liability if its thread dies. A thread that pins an epoch and then crashes or exits without unpinning would hold MinActiveEpoch down forever — freezing eviction across the whole cache. Two safeguards catch it: each slot is owned by a CriticalFinalizerObject that releases it when the thread is collected, and the MinActiveEpoch scan does a Thread.IsAlive liveness check, reclaiming any slot whose owner has died. The grace period is robust to threads that never come back.

🎯 The takeaway

Reference counting is the reflex answer to "don't free this while someone's using it," and for a lot of code it's the right one. But it answers a harder question than most callers ask. When you don't need who or how many — only is it safe yet — epoch-based reclamation turns O(N) contended bookkeeping into O(1): publish a number on the way in, tick a number on the way out, and let a grace period retire everything at once. The cost is that protection is coarse, so it fits workloads whose units of work are bounded — which, for a database built for game ticks and simulation frames, they are by construction.

That's the pattern worth keeping even if you never touch Typhon: before you reach for a counter, check whether you actually need the count, or just the guarantee.

⏭️ What's next

Post #7: MVCC at Microsecond Scale: Snapshot Isolation Without Cloning Rows. Those epoch-stamped pages are where revision chains live — every update appends a new version instead of overwriting, readers see a frozen snapshot, and old revisions get retired by the same kind of grace-period reasoning you just read. Next post pulls that thread.

Follow the GitHub repo for source and benchmarks, or subscribe via RSS.

Azure Table Storage: The Middle Ground Between a SQL Table and a Document Database

Manohari Jayachandran — Fri, 26 Jun 2026 15:01:28 +0000

I published a comparison of Azure SQL, Cosmos DB, and Blob Storage a little while back. Looking back at it, Azure Table Storage was a real gap - it sits in a genuinely useful middle position between a relational table and a full document database, and it deserves its own proper explanation rather than a passing mention. This post fills that in, with real C# code and a few lessons from using it in production alongside Azure Service Bus at Blue Yonder.

What Azure Table Storage Actually Is

Azure Table Storage is a NoSQL key-value store for large amounts of structured, non-relational data. It occupies an interesting middle position - simpler and considerably cheaper than Cosmos DB, while still being schema-flexible in a way Azure SQL fundamentally is not. Despite the name, it has nothing to do with SQL tables in the relational sense - "table" here is closer to a giant, partitioned dictionary than a database table with fixed columns.

Azure SQL is a filing cabinet with identical forms in every folder.
Cosmos DB is a box of index cards where every card can say something different.
Table Storage sits somewhere in between - a long row of labeled shoeboxes on a shelf, where each shoebox holds many index cards, and every card in a shoebox can still carry different fields, but things get found quickly specifically because you know which shoebox to check first.

Where Table Storage Actually Sits

Against Azure SQL, Table Storage trades real relational power and joins for dramatically lower cost and a flexible schema per entity.
Against Cosmos DB, it trades rich query capability and global distribution for an even simpler pricing model and operational footprint. It is genuinely the cheapest of the three options, and the one with the most limited query language by a meaningful margin.

Core Concepts

A Table is a collection of entities - schema-flexible in spirit, similar to a Cosmos DB container, but considerably simpler in practice.
An Entity is a single row-like record, identified by a PartitionKey and a RowKey, plus any number of additional properties beyond those two required fields.
The PartitionKey groups related entities together for fast lookup and horizontal scalability - exactly the same kind of design decision as a partition key in Cosmos DB, and just as consequential if chosen poorly. The RowKey uniquely identifies an entity within its specific partition.

Together, PartitionKey and RowKey form an entity's complete unique identifier within the table.

A practical example makes the flexibility clear: two log entities sharing the same partition, representing the same month, can still carry entirely different fields if a logging format changes over time - no schema migration required, the same flexibility spirit as Cosmos DB, at a fraction of the operating cost.

Reading and Writing From C

After installing the Azure.Data.Tables NuGet package, working with Table Storage from C# follows a straightforward pattern: construct a TableClient pointed at a specific table, then read and write TableEntity objects using their PartitionKey and RowKey.

A point read - fetching one specific entity by its exact PartitionKey and RowKey - is the fastest possible operation the service offers, conceptually identical to a point read in Cosmos DB. Querying within a single partition using a filter expression remains fast and well-supported. Updates and deletes follow the same PartitionKey-plus-RowKey addressing scheme throughout.

The Query Language, and Its Real Limitation

This is where Table Storage is honest about being the cheapest, simplest option of the three. There is no SQL-like query language the way Cosmos DB offers one. Filtering uses OData-style string expressions - reasonably readable for simple conditions, but with no joins, no aggregates, and no server-side grouping available at all.

A filter checking for entities in a specific partition with a specific status level reads naturally enough as an OData expression,and produces broadly similar results to the equivalent Azure SQL or Cosmos DB query for that simple case. The difference becomes obvious the moment a query needs a join, an aggregate like a count or an average, or needs to span many partitions efficiently. Table Storage simply does not offer that capability - querying happens within a partition, or by scanning across all partitions, with nothing in between.

Why The Limitation Is Actually The Point

Table Storage deliberately trades query power for extreme low cost and high throughput on simple lookups. It is the right tool specifically when the access pattern is almost always "give me everything in partition X" or "give me the one entity at this exact PartitionKey and RowKey combination" - when joins, aggregates, and complex filtering are simply not needed, when data volume runs into the millions of records but the logic per record stays simple, and when cost matters more than query flexibility.

Real-world scenarios that fit this profile well include application logging and audit trails, IoT telemetry keyed by device identifier and timestamp, session state keyed by session identifier, simple lookup caches, and a message or event audit trail running alongside a service like Azure Service Bus - logging every message processed, keyed by date and message identifier, without needing the query power or cost of a full database to answer a simple question like "did this message get processed, and when." At Blue Yonder, Table Storage and Service Bus worked together in exactly this way, with Service Bus handling actual message delivery while Table Storage held a lightweight, low-cost record of what had moved through the pipeline.

A Genuine Naming Trap Worth Knowing

Confusingly, Cosmos DB also offers its own "Table API" that uses the exact same entity model - PartitionKey and RowKey - and is largely code-compatible with standalone Table Storage. Azure Table Storage, the storage-account-based service covered in this post, remains the cheapest option, with no throughput SLA beyond standard storage account limits and the simplest possible pricing model. Cosmos DB's Table API uses the identical programming model but runs on Cosmos DB's underlying infrastructure - global distribution, guaranteed throughput, multi-region replication - at Cosmos DB pricing.

The practical migration path this enables is genuinely useful: start on plain Table Storage for cost efficiency, and if global distribution or guaranteed low-latency service levels become necessary later, migrate to Cosmos DB's Table API with minimal code changes, since the entity model is shared between them.

An Honest Three-Way Comparison

Choose Azure SQL when data is relational, real joins and aggregates are genuinely needed, and the data shape stays consistent across records.
Choose Table Storage when data volume is high and the access pattern is simple - point lookups or partition scans - and cost matters more than
query flexibility.
Choose Cosmos DB when document shape varies meaningfully between records, real query power over JSON structure is needed, or global distribution and guaranteed low-latency reads are genuine requirements.

Key Lessons

Table Storage and Cosmos DB share an entity model but are priced and operated in completely different ways - know precisely which one is actually being provisioned before committing to either.
The OData filter syntax is genuinely limited. If a query needs a join or an aggregate, Table Storage is the wrong tool for that job regardless of how attractive its cost looks.
PartitionKey design matters here exactly as much as it does in Cosmos DB get it wrong and partition scans become expensive as data grows.
Table Storage is frequently the right default first choice for logging and telemetry data specifically because that access pattern is almost always simple key-based lookups rather than anything more complex.
Pairing it with a messaging service like Service Bus for a lightweight audit trail is a genuinely useful pattern worth knowing, not just a theoretical one.

Summary

Azure Table Storage fills the real gap between a relational table and a full document database - schema-flexible in the same spirit as Cosmos DB, but priced and queried far more simply, with genuine limitations on what it can be asked to do. It earns its place specifically when the access pattern is simple and the volume is high. It was a gap worth closing properly, with real production context behind it rather than just a theoretical comparison.

Originally published at TechStack Blog:
https://www.techstackblog.com/post.html?slug=azure-table-storage-explained

Related reading on TechStack Blog:
https://www.techstackblog.com/post.html?slug=azure-cosmos-db-blob-storage

More from TechStack Blog, by category:
Azure: https://www.techstackblog.com/category.html?cat=azure
Database: https://www.techstackblog.com/category.html?cat=database

Follow for weekly posts on Azure, C#, and cloud engineering.

GitHub Copilot CLI Slash Commands Every .NET Developer Should Know

Vikrant Bagal — Fri, 26 Jun 2026 13:47:50 +0000

What if you could generate C# unit tests, refactor your .NET code, and manage your GitHub repo — all without leaving your terminal?

GitHub Copilot CLI brings AI-powered development directly to your command line. You probably already know Copilot from your IDE, but the CLI version offers something different: full natural‑language control over your terminal context. You get an interactive, session-aware assistant that live in your shell, understands file contents, and runs commands.

As a .NET developer, this means you can ask Copilot CLI to scaffold an ASP.NET Core React project, explain a Program.cs file, or debug an Entity Framework migration — and it sees the same values you see. No copy‑pasting. No context‑switching.

This guide walks you through the most useful Copilot CLI slash commands that will genuinely change how you work, especially if you are in the .NET ecosystem. Let me start with the basics.

Getting Started: Installing and Authenticating Copilot CLI

First, install the official GitHub Copilot CLI extension for GitHub CLI. If you already have gh installed, this is a single command:

gh extension install github/copilot-cli

Then authenticate. Ensure you have an active GitHub Copilot subscription (Individual, Business, or Enterprise). Run:

gh copilot auth-status

If not authenticated, sign in:

gh auth login

Now launch the interactive Copilot CLI session:

gh copilot

You will enter a REPL-style interface where you type natural language prompts and Copilot CLI responds with code, commands, or analysis — and can execute commands in the middle of a session. This is where the real power begins, specifically through slash commands — the hidden gem that transforms this from a chatbot into a programmable AI terminal.

/model: Switch AI Models On the Fly

One of the first commands you should learn is /model. It lets you change the underlying AI model during a session. This matters because different models handle different tasks better — GPT-4o might excel at complex C# refactoring, while Claude Sonnet might be faster for boilerplate generation.

Inside the copilot prompt:
/model

This displays the current model and lets you switch. To set it directly:

/model gpt-4o
/model claude-sonnet
/model gemini-2.5-flash-preview

This flexibility is huge for .NET developers. You can test your EF Core model generation or ASP.NET Minimal API setup against different models without changing any IDE settings. Just type /model, pick one, and continue your session.

/delegate: Let AI Agent Handle Your Repetitive .NET Tasks

The /delegate command is Copilot CLI's most powerful time-saver. It offloads tasks to a cloud‑hosted AI agent that works asynchronously — meaning you continue coding while Copilot CLI works in the background.

/delegate Write xUnit tests for OrderService.cs covering edge cases

/delegate Refactor the CustomerController to use minimal APIs

/delegate Run dotnet build, analyze warnings, and suggest fixes

The agent runs in a sandboxed environment with your repo context, completes the task, and returns results. This is particularly useful for .NET workloads:

Generating test projects with realistic test data and mocking frameworks (Moq, NSubstitute)
Scaffolding new ASP.NET Core projects from scratch or from existing models
Investigating NuGet package compatibility during version upgrades
Running dotnet CLI commands: dotnet build, dotnet Ef migrations add, dotnet publish etc. — without leaving Copilot CLI

Return on investment: Instead of manually switching context, writing the test yourself, and then debugging, you describe intent in natural language and review the output when ready.

/context and /compact: Control Token Usage in Large .NET Solutions

Large .NET solutions with dozens of projects generate massive context. Every token costs money and slows responses. The /context and /compact commands let you manage this explicitly:

/context

This shows current context usage, file count, and approximate tokens consumed. Essential before asking Copilot CLI to analyze a 50‑project solution.

When context gets too large, use /compact:

/compact

Copilot CLI summarizes the conversation history, reducing token pressure — like minimizing a window but keeping the important state. For .NET developers working with monolithic repositories or large dotnet new‑generated microservice templates, this keeps responsiveness high and costs predictable. You can also explicitly exclude folders:

/compact --exclude "**/bin", "**/obj", "**/node_modules"

This prevents build artifacts and dependencies from polluting the context window during Copilot CLI sessions.

/allow-all and /deny-Tool: Manage Permissions Safely

By default, Copilot CLI asks for confirmation before executing any shell command. For .NET developers running dotnet build, migrations, or publish operations, this can cause permission fatigue. Slash commands let you configure trusted tools:

/allow-all

Gives blanket permission. Risky in production repos but fine locally — Copilot CLI moves faster, executing dotnet build and dotnet run without prompting you each time. To be more surgical:

/deny-tool dotnet-ef
/deny-tool docker

Useful when you trust dotnet build but want manual control over database migrations or container commands. Narrow permissions keep you safe while automating the tasks you trust.

The Bottom Line

As a .NET developer, you spend a lot of time in the terminal. GitHub Copilot CLI slash commands — /model, /delegate, /compact, /allow‑all — let you keep that flow.

Start small: open gh copilot today and try /model to switch models on a single task. Then experiment with /delegate for your next refactoring repetition. Once you feel the compound effect on daily .NET tasks, you will rarely go back to manually typing every command yourself.

One hyphen, two tenants, one signing key

authagonal — Fri, 26 Jun 2026 13:00:00 +0000

Two of our tenants were the same tenant. They had different names, different signups, and different billing rows. They also shared a database and a token-signing key, and none of the three of us, the two tenants or us, had any idea. This is the story of the one-line function that merged them, why every layer of the system looked perfectly correct while it happened, and why a pre-launch audit is the cheapest insurance you will ever buy.

Multi-tenant auth has exactly one job it cannot get wrong: keep tenants apart. Acme's users, Acme's sessions, and above all Acme's signing key must never be reachable by anyone else. The signing key is the crown jewel. Whoever can sign with Acme's key can mint a token that Acme's own auth server will accept as genuine, for any user, with any role, no password required. So every per-tenant resource we create, every storage table and every key, is namespaced by the tenant's slug. Get that namespacing right and tenants are islands. Get it subtly wrong and they quietly become the same place.

The one-line bug

Here is the function that turns a tenant slug into the prefix we name its storage and keys with. Read the doc comment. It documents the bug as if it were a feature.

/// Derive the table name prefix from a tenant slug by stripping hyphens.
/// E.g. "acme-corp" → "acmecorp".
public static string GetTablePrefix(string tenantSlug)
{
    return tenantSlug.Replace("-", "");
}

Replace("-", ""). It strips hyphens. The intent was housekeeping: slugs flow into Azure Table names and Vault key names, which have their own character rules, so we sanitized them. The trouble is that stripping characters is a lossy transform, and a lossy transform on an identifier is not injective. acme-corp and acmecorp both come out as acmecorp. So do ac-me-corp and acme--corp. Distinct slugs, one namespace.

That namespace is everything downstream. The user table is {prefix}-Users. And the per-tenant signing key is, verbatim, this:

private string GetKeyName() => $"signing-{ShardRouter.GetTablePrefix(_tenantContext.Slug)}";

So acme-corp and acmecorp do not merely share a user list. They sign their tokens with the same signing-acmecorp key in Vault. A token minted for one is, byte for byte, a validly signed token for the other. If you can register a slug that collapses to the same prefix as an existing tenant, you can issue yourself tokens their auth server trusts completely. Cross-tenant account takeover, and the exploit is "sign up with a hyphen."

Why nothing caught it

The unsettling part is how ordinary every layer looked. Signup validated the slug and saw a fresh, unused string. Provisioning created a tenant record keyed by the full slug, acme-corp, which is genuinely distinct from acmecorp in the control plane. Token validation derived the key from the slug and verified happily. Every component did its job correctly on its own input.

Nothing in the system ever compared two slugs' prefixes, because no single component owned the invariant "a slug maps to exactly one namespace." The collision lived in the gap between a slug, which the control plane keys on, and a prefix, which storage and Vault key on. Nobody was standing in that gap. This is the signature of the most dangerous class of bug: not a check anyone forgot, but an assumption nobody knew they were making.

The second collision, for free

The same lossy transform had a second victim. Our internal system tenants are named by suffix: {slug}-admin holds a tenant's portal team, {slug}-sandbox holds its test environment. Run those through the same de-hyphenator and acme-admin becomes acmeadmin. Which means a customer who registered the slug acmeadmin would collapse onto the prefix of Acme's admin tenant, the one place that is supposed to be more privileged than the customer, not shared with one.

One stripping function, two different isolation boundaries at risk: tenant to tenant, and tenant to its own control plane. When a single line threatens two unrelated boundaries, that is the tell of a root-cause bug rather than a surface one. The fix has to land on the transform, not on either symptom.

The fix: injective by construction

The instinct is to make the prefix function smarter. Escape the hyphens, hash the slug, base32-encode it. Every one of those is still a transform you have to prove injective forever, against every future change, by someone who may not know why it matters. The cheaper and far more durable fix is to remove the transform's freedom entirely: constrain the input so the transform is the identity.

// Lowercase alphanumeric ONLY, no hyphens. Forbidding hyphens makes prefix == slug,
// so distinct slugs can never share a data store or signing key.
if (!slug.All(c => (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')))
    return false;

Slugs are now lowercase letters and digits, nothing else. With no hyphens to strip, GetTablePrefix has nothing to do, prefix == slug holds by construction, and two distinct slugs can never share a namespace again. We also reject the reserved names and any slug ending in admin or sandbox, which closes the system-tenant collision in the same line. The validity check is the narrow point where a slug first becomes a namespace, so that is exactly where the one-to-one guarantee belongs.

We then re-assert the same rule one more time, at the provisioning chokepoint. There are two doors a slug can enter through, self-service signup and admin-driven provisioning, and a security invariant defended at only one of two doors is defended at neither.

Why we are telling you

We found this in a pre-launch security audit of our own product, before a single paying customer existed, which is the only acceptable time to find it. No tenant was ever merged in production. But it is a humbling bug, because it is not a missing check or a weak algorithm. It is a helper that does something entirely reasonable, sanitize a string, in a place where "reasonable" and "injective" turn out to be different words.

The lesson outlived the fix. Any function that turns user-controlled input into the name of a security boundary, a table, a key, a namespace, a path, must be injective, and you should enforce that at the narrowest point where the mapping is created, not hope it survives every layer downstream. A normalize step, lowercase, trim, strip, collapse, is precisely where two identities quietly become one.

It is the same principle the whole product is built on. Security is not a tier you graduate into; it is the floor. Every isolation guarantee, every signing key, and every security feature we ship, SSO and SAML, SCIM, MFA, audit export, is on at every plan, because the alternative is the kind of thing you find at 2am instead of in an audit. See what's included.

Ensuring Thread Safety — .NET core-centric

Hossein Esmati — Fri, 26 Jun 2026 12:35:51 +0000

Prefer immutability

What: Make data read-only after construction. Instead of editing objects, create new ones.

Why: If nothing changes, many threads can read safely with no locks.

How (.NET):

public readonly record struct Money(decimal Amount, string Currency);

public record Order(Guid Id, IReadOnlyList<OrderLine> Lines)
{
    public Order AddLine(OrderLine line) => this with { Lines = Lines.Append(line).ToList() };
}

Use record/readonly struct, IReadOnlyList<>, and with (copy-on-write).
Keep collections immutable (ImmutableList<T>, ImmutableDictionary<K,V>).

Avoid shared state

What: Don’t let unrelated code touch the same mutable object.

Why: If each operation owns its data, there’s nothing to synchronize.

How:

Per-request scope: create new service instances that hold request-specific state.
No static mutable fields; if you must cache, use ConcurrentDictionary:

private static readonly ConcurrentDictionary<string, Widget> _cache = new();
var widget = _cache.GetOrAdd(key, k => LoadWidget(k));

Use `lock` / `SemaphoreSlim` cautiously

What: Synchronization primitives that serialize access to critical sections.

When:

Short, minimal critical sections where mutation is unavoidable.
lock for synchronous code; SemaphoreSlim when await is involved (never block in async code).

Patterns & pitfalls:

private readonly object _gate = new();

void Update()
{
    lock (_gate) // keep work tiny inside
    {
        // mutate a small piece of shared state
        _count++;
    }
}

private readonly SemaphoreSlim _sem = new(1,1);

async Task UpdateAsync()
{
    await _sem.WaitAsync();
    try { _count++; }
    finally { _sem.Release(); }
}

Never lock(this) or a public object (external code could deadlock you).
Keep lock duration short; avoid I/O under locks.
If multiple locks are needed, fix a global order to prevent deadlocks.

Atomic counters (avoid locks entirely):

Interlocked.Increment(ref _count);

Leverage actor-style or message queues

What: Push work as messages to a single-threaded “actor” that owns its state. Or use an external queue/bus so workers don’t share memory.

Why: Eliminates shared writes; logic becomes “handle one message at a time.”

How (lightweight actors with Channels):

public sealed class CounterActor
{
    private readonly Channel<Action<State>> _in = Channel.CreateUnbounded<Action<State>>();
    private readonly State _state = new();

    public CounterActor()
    {
        _ = Task.Run(async () =>
        {
            await foreach (var msg in _in.Reader.ReadAllAsync())
                msg(_state); // single-threaded access
        });
    }

    public ValueTask Tell(Action<State> msg) => _in.Writer.WriteAsync(msg);

    public sealed class State { public int Count; }
}

At scale: use Orleans/Akka.NET (virtual actors) or external queues (Azure Service Bus/Storage Queues) to process messages concurrently without shared memory.

Timeouts, cancellation, and async correctness

Always pass CancellationToken so long operations end promptly—reduces lock contention.
In ASP.NET Core, never block the thread (.Result, .Wait()); use await to avoid thread pool starvation.

Observability for thread-safety issues

Metric: lock contention, queue length, actor mailbox size.
Logs with correlation IDs to trace races.
Load/stress tests that hammer critical paths (many parallel tasks) to catch races early.

Quick decision guide

Can it be immutable? Do that first.
Must it be shared & mutable? Encapsulate state behind an actor or a queue.
Tiny unavoidable mutation? Guard with Interlocked/lock/SemaphoreSlim (short, ordered, no I/O).
Collections? Prefer immutable or Concurrent* types.

Synchronous vs asynchronous in .NET core - how decide

Hossein Esmati — Fri, 26 Jun 2026 12:35:41 +0000

Rule of thumb

If your action waits on something external, make it async. If it’s instant CPU, keep it sync; for expensive CPU, offload.

The core idea

Async shines for I/O-bound work (DB calls, HTTP calls, queues, files). It frees the request thread while waiting, so the server can serve more requests with the same thread pool.
Sync is fine for trivial, short CPU work (formatting, small calculations) where you’re not awaiting anything and the handler returns in a few milliseconds.

When to choose async

You call EF Core (SaveChangesAsync, ToListAsync), HttpClient, Azure SDK (ServiceBusClient, BlobClient), file I/O, or any API with Async methods.
You expect latency from a dependency (tens–hundreds of ms).
You need cancellation and timeouts (propagate HttpContext.RequestAborted).

When sync is acceptable

The action is pure CPU and trivial (e.g., quick math, mapping, input validation) and returns immediately.
There are no I/O waits and no benefit from freeing the thread.

If it’s CPU-heavy (image processing, big JSON transforms), do not just make it async—offload to a background queue/worker or a separate compute service. Async won’t make CPU faster.

Pitfalls to avoid

Don’t block async: never use .Result / .Wait() on Tasks (deadlocks/thread-pool starvation).
Async all the way down: if the controller is async, downstream calls should be too.
Don’t fake async: returning Task.Run around synchronous I/O just burns threads.
Keep concurrency bounded when fanning out to multiple I/O calls.

Mini decision checklist

Any I/O? → Use async (end-to-end).
Pure CPU?

Tiny (≤ a few ms) → Sync is fine.
Heavy/variable → Offload to background worker; controller returns 202/Location or uses a queue.

ASP.NET Core examples

Async (I/O-bound) — recommended

[ApiController]
[Route("orders")]
public class OrdersController : ControllerBase
{
    private readonly OrdersDbContext _db;
    private readonly HttpClient _http;

    public OrdersController(OrdersDbContext db, IHttpClientFactory f)
    {
        _db = db;
        _http = f.CreateClient("catalog");
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<OrderDto>> Get(string id, CancellationToken ct)
    {
        var order = await _db.Orders.FindAsync([id], ct);
        if (order is null) return NotFound();

        // Call another service
        var resp = await _http.GetAsync($"/inventory/{order.Sku}", ct);
        resp.EnsureSuccessStatusCode();
        var inv = await resp.Content.ReadFromJsonAsync<InventoryDto>(cancellationToken: ct);

        return Ok(new OrderDto(order, inv));
    }
}

Sync (trivial CPU) — acceptable

[HttpGet("ping")]
public ActionResult<string> Ping() => "pong"; // no I/O, returns immediately

CPU-heavy work — offload rather than “asyncifying”

// Controller: accept request, enqueue, return 202
[HttpPost("render")]
public async Task<IActionResult> Render(RenderRequest req, [FromServices] IBackgroundQueue queue)
{
    var jobId = Guid.NewGuid().ToString("N");
    await queue.EnqueueAsync(jobId, req);
    return Accepted($"/render/{jobId}");
}

// Hosted service: single place that uses CPU, bounded concurrency
public class RenderWorker : BackgroundService
{
    private readonly IBackgroundQueue _q;
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var job in _q.DequeueAllAsync(stoppingToken))
        {
            // CPU-bound work here (e.g., image/video), controlled degree of parallelism
        }
    }
}

Tuning & tips

Pass CancellationToken from HttpContext.RequestAborted.
Use IHttpClientFactory and async Azure SDKs.
For streaming, expose IAsyncEnumerable<T> or chunked responses (async).
In ASP.NET Core there’s no UI SynchronizationContext, so ConfigureAwait(false) is usually unnecessary.

Shared Libraries Management in .NET and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:30:29 +0000

Core Principle: Avoid Domain Coupling

The fundamental rule is simple: shared libraries should contain only cross-cutting concerns, never domain logic. When you share domain entities across services, you break bounded context boundaries and create the very coupling microservices aim to eliminate.

Recommended Shared Library Structure

Solution Structure:
├── src/
│   ├── Services/
│   │   ├── OrderService/
│   │   │   └── OrderService.Domain/        # Private domain model
│   │   ├── CustomerService/
│   │   │   └── CustomerService.Domain/     # Private domain model
│   │   └── PaymentService/
│   │       └── PaymentService.Domain/      # Private domain model
│   └── Shared/
│       ├── Company.Common/                  # ✅ Utilities, extensions
│       ├── Company.Observability/           # ✅ Telemetry, logging
│       ├── Company.Messaging/               # ✅ Message bus abstractions
│       ├── Company.Authentication/          # ✅ Auth middleware
│       ├── Company.Contracts/               # ✅ Integration contracts (DTOs)
│       └── Company.ServiceDefaults/         # ✅ .NET Aspire defaults

What Belongs in Shared Libraries

1. Cross-Cutting Utilities (Company.Common)

Infrastructure code that has no business logic:

// Company.Common - Extensions and utilities
namespace Company.Common.Extensions;

public static class DateTimeExtensions
{
    public static DateTime ToUtc(this DateTime dateTime)
    {
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }

    public static DateOnly ToDateOnly(this DateTime dateTime)
        => DateOnly.FromDateTime(dateTime);
}

public static class StringExtensions
{
    public static bool IsNullOrWhiteSpace([NotNullWhen(false)] this string? value)
        => string.IsNullOrWhiteSpace(value);
}

// Result pattern for consistent error handling
public readonly record struct Result<T>
{
    public required T Value { get; init; }
    public required bool IsSuccess { get; init; }
    public string? Error { get; init; }

    public static Result<T> Success(T value) 
        => new() { Value = value, IsSuccess = true };

    public static Result<T> Failure(string error) 
        => new() { Value = default!, IsSuccess = false, Error = error };
}

2. Observability Infrastructure (Company.Observability)

Leveraging .NET 9's enhanced observability features:

// Company.Observability - Structured logging and telemetry
namespace Company.Observability;

public static class ObservabilityExtensions
{
    public static IHostApplicationBuilder AddCompanyObservability(
        this IHostApplicationBuilder builder)
    {
        // .NET 9 enhanced metrics
        builder.Services.AddMetrics();

        // OpenTelemetry with Azure Monitor
        builder.Services.AddOpenTelemetry()
            .WithMetrics(metrics =>
            {
                metrics.AddRuntimeInstrumentation()
                       .AddAspNetCoreInstrumentation()
                       .AddHttpClientInstrumentation();
            })
            .WithTracing(tracing =>
            {
                tracing.AddAspNetCoreInstrumentation()
                       .AddHttpClientInstrumentation()
                       .AddEntityFrameworkCoreInstrumentation();

                if (builder.Environment.IsProduction())
                {
                    tracing.AddAzureMonitorTraceExporter(options =>
                    {
                        options.ConnectionString = builder.Configuration
                            .GetConnectionString("ApplicationInsights");
                    });
                }
            });

        return builder;
    }
}

// Structured logging with LoggerMessage source generators (.NET 9)
public static partial class Log
{
    [LoggerMessage(
        EventId = 1001,
        Level = LogLevel.Information,
        Message = "Processing order {OrderId} for customer {CustomerId}")]
    public static partial void ProcessingOrder(
        ILogger logger, 
        Guid orderId, 
        Guid customerId);

    [LoggerMessage(
        EventId = 1002,
        Level = LogLevel.Error,
        Message = "Failed to process order {OrderId}")]
    public static partial void OrderProcessingFailed(
        ILogger logger, 
        Exception exception,
        Guid orderId);
}

3. Messaging Abstractions (Company.Messaging)

Event-driven communication patterns without business logic:

// Company.Messaging - Message contracts and infrastructure
namespace Company.Messaging;

// Base interfaces - no business rules
public interface IEvent
{
    Guid EventId { get; }
    DateTime OccurredAtUtc { get; }
    string EventType { get; }
}

public interface ICommand
{
    Guid CommandId { get; }
    string CommandType { get; }
}

// Abstract base with common behavior
public abstract record EventBase : IEvent
{
    public Guid EventId { get; init; } = Guid.NewGuid();
    public DateTime OccurredAtUtc { get; init; } = DateTime.UtcNow;
    public string EventType { get; init; }

    protected EventBase()
    {
        EventType = GetType().Name;
    }
}

// Generic message handlers
public interface IEventHandler<in TEvent> where TEvent : IEvent
{
    Task HandleAsync(TEvent @event, CancellationToken cancellationToken = default);
}

public interface ICommandHandler<in TCommand> where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken cancellationToken = default);
}

4. Integration Contracts (Company.Contracts)

Lightweight DTOs for inter-service communication - no domain logic, just data transfer:

// Company.Contracts - Integration events (versioned)
namespace Company.Contracts.Orders.V1;

// Integration event - published across service boundaries
public sealed record OrderCreatedEvent(
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount,
    DateTime CreatedAtUtc,
    string Currency = "USD") : EventBase;

// Integration event with versioning
public sealed record OrderStatusChangedEvent(
    Guid OrderId,
    string Status,
    DateTime ChangedAtUtc,
    string? Reason = null) : EventBase;

namespace Company.Contracts.Customers.V1;

public sealed record CustomerRegisteredEvent(
    Guid CustomerId,
    string Email,
    DateTime RegisteredAtUtc) : EventBase;

5. .NET Aspire Service Defaults (Company.ServiceDefaults)

Standardized service configuration for .NET Aspire orchestration:

// Company.ServiceDefaults - Aspire-ready defaults
namespace Company.ServiceDefaults;

public static class ServiceDefaultsExtensions
{
    public static IHostApplicationBuilder AddCompanyServiceDefaults(
        this IHostApplicationBuilder builder)
    {
        // Service discovery
        builder.Services.AddServiceDiscovery();

        // Resilience with Polly
        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            http.AddStandardResilienceHandler();
            http.AddServiceDiscovery();
        });

        // Health checks
        builder.Services.AddHealthChecks()
            .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);

        // Observability
        builder.AddCompanyObservability();

        // OpenAPI with scalar (new in .NET 9)
        builder.Services.AddOpenApi();

        return builder;
    }

    public static WebApplication MapCompanyDefaultEndpoints(
        this WebApplication app)
    {
        // Health checks
        app.MapHealthChecks("/health");
        app.MapHealthChecks("/alive", new() 
        {
            Predicate = r => r.Tags.Contains("live")
        });

        // OpenAPI
        if (app.Environment.IsDevelopment())
        {
            app.MapOpenApi();
            app.MapScalarApiReference(); // New in .NET 9
        }

        return app;
    }
}

What Does NOT Belong in Shared Libraries

❌ Shared Domain Models

This is the most common mistake:

// ❌ BAD: Company.Domain - DO NOT DO THIS
public class Order  // Shared domain entity - creates coupling!
{
    public Guid Id { get; set; }
    public Guid CustomerId { get; set; }
    public List<OrderLine> Lines { get; set; } = [];
    public OrderStatus Status { get; set; }

    public void AddLine(string productId, int quantity, decimal price)
    {
        // Business logic shared across services = coupling
        Lines.Add(new OrderLine(productId, quantity, price));
    }

    public decimal CalculateTotal() => Lines.Sum(l => l.Price * l.Quantity);
}

Why this is harmful:

Breaks bounded context boundaries
Forces all services to use the same domain model
Creates deployment dependencies
Prevents independent evolution
Violates DDD principles

✅ Correct Approach: Private Domain Models

Each service maintains its own domain model:

// ✅ GOOD: OrderService.Domain (private to OrderService)
namespace OrderService.Domain;

public sealed class Order
{
    private readonly List<OrderLine> _lines = [];

    public Guid Id { get; private set; }
    public Guid CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public decimal Total => _lines.Sum(l => l.LineTotal);
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();

    // Rich domain behavior specific to this service
    public Result<OrderLine> AddLine(string productId, decimal price, int quantity)
    {
        if (quantity <= 0)
            return Result<OrderLine>.Failure("Quantity must be positive");

        if (price < 0)
            return Result<OrderLine>.Failure("Price cannot be negative");

        var line = new OrderLine(Guid.NewGuid(), productId, price, quantity);
        _lines.Add(line);
        return Result<OrderLine>.Success(line);
    }

    public void MarkAsConfirmed()
    {
        if (Status != OrderStatus.Pending)
            throw new InvalidOperationException("Only pending orders can be confirmed");

        Status = OrderStatus.Confirmed;
    }

    // Convert to integration event for publishing
    public OrderCreatedEvent ToIntegrationEvent()
    {
        return new OrderCreatedEvent(
            Id, 
            CustomerId, 
            Total, 
            DateTime.UtcNow);
    }
}

// ✅ GOOD: ShippingService.Domain (different perspective on "Order")
namespace ShippingService.Domain;

// Shipping service has its own view of an order
public sealed class ShipmentOrder
{
    public Guid OrderId { get; private set; }
    public Address ShippingAddress { get; private set; }
    public List<ShipmentItem> Items { get; private set; } = [];
    public ShipmentStatus Status { get; private set; }

    // Different behavior, different invariants
    public void PrepareForShipment()
    {
        if (Items.Count == 0)
            throw new InvalidOperationException("Cannot ship empty order");

        Status = ShipmentStatus.ReadyForPickup;
    }

    // Maps from integration event
    public static ShipmentOrder FromOrderCreatedEvent(
        OrderCreatedEvent evt, 
        Address address)
    {
        return new ShipmentOrder
        {
            OrderId = evt.OrderId,
            ShippingAddress = address,
            Status = ShipmentStatus.Pending
        };
    }
}

Package Management with NuGet

Semantic Versioning Strategy

Follow Semantic Versioning and .NET Versioning Guidelines:

<!-- Directory.Build.props -->
<Project>
  <PropertyGroup>
    <!-- Central version management -->
    <VersionPrefix>2.1.0</VersionPrefix>
    <VersionSuffix Condition="'$(Configuration)' != 'Release'">preview</VersionSuffix>

    <!-- .NET 9 settings -->
    <TargetFramework>net9.0</TargetFramework>
    <LangVersion>13.0</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>

    <!-- Package defaults -->
    <Authors>Company Engineering</Authors>
    <Company>YourCompany</Company>
    <PackageProjectUrl>https://nova-globen.se</PackageProjectUrl>
    <RepositoryUrl>https://github.com/desmati/shared-libs</RepositoryUrl>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>
</Project>

<!-- Company.Common.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Company.Common</PackageId>
    <Description>Common utilities and extensions for Company microservices</Description>
    <PackageTags>utilities;extensions;microservices</PackageTags>
    <Version>$(VersionPrefix)$(VersionSuffix)</Version>
  </PropertyGroup>

  <ItemGroup>
    <!-- Source Link for better debugging -->
    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>

    <!-- Nullable annotations -->
    <PackageReference Include="System.Diagnostics.CodeAnalysis" Version="9.0.0" />
  </ItemGroup>

  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="\" />
  </ItemGroup>
</Project>

Versioning Strategies

Strategy 1: Independent Versioning (Recommended)

Each package evolves independently based on its own changes:

<!-- Company.Common - Version 2.1.0 -->
<PropertyGroup>
  <Version>2.1.0</Version>
</PropertyGroup>

<!-- Company.Messaging - Version 1.8.3 (depends on Common) -->
<PropertyGroup>
  <Version>1.8.3</Version>
</PropertyGroup>
<ItemGroup>
  <!-- Range allows patch and minor updates -->
  <PackageReference Include="Company.Common" Version="[2.1.0,3.0.0)" />
</ItemGroup>

<!-- Company.Contracts - Version 3.4.1 (depends on Messaging) -->
<PropertyGroup>
  <Version>3.4.1</Version>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Company.Messaging" Version="[1.8.0,2.0.0)" />
</ItemGroup>

Advantages:

Each package version reflects its actual changes
Clear semantic meaning
Services can upgrade dependencies independently
Reduces unnecessary updates

Use when: Packages have different rates of change and can evolve independently.

Strategy 2: Central Package Management (CPM)

.NET supports centralized version management:

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup>
    <!-- Internal packages -->
    <PackageVersion Include="Company.Common" Version="2.1.0" />
    <PackageVersion Include="Company.Messaging" Version="1.8.3" />
    <PackageVersion Include="Company.Contracts" Version="3.4.1" />
    <PackageVersion Include="Company.Observability" Version="2.0.5" />

    <!-- External dependencies -->
    <PackageVersion Include="Azure.Messaging.ServiceBus" Version="7.18.1" />
    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="9.0.0" />
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>
</Project>

<!-- In project files, just reference without version -->
<ItemGroup>
  <PackageReference Include="Company.Common" />
  <PackageReference Include="Company.Messaging" />
</ItemGroup>

Advantages:

Single source of truth for versions
Easier to ensure consistency
Prevents version conflicts
Better for monorepo scenarios

Strategy 3: Synchronized Suite Versioning

When packages are released together as a cohesive suite:

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CompanySuiteVersion>3.0.0</CompanySuiteVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Company.Common" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.Messaging" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.Contracts" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.Observability" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.ServiceDefaults" Version="$(CompanySuiteVersion)" />
  </ItemGroup>
</Project>

Use when:

Packages are designed to work together
Breaking changes affect multiple packages
Simplified mental model for consumers
Regular coordinated releases

Hotfix and Patching Strategy

Scenario: Critical Bug in Company.Common

Current State:

Company.Common: 2.1.0
Company.Messaging: 1.8.3 (depends on Common [2.1.0, 3.0.0))
Company.Contracts: 3.4.1 (depends on Messaging)

Hotfix Process:

# 1. Create hotfix branch from release tag
git checkout -b hotfix/2.1.1 v2.1.0

# 2. Fix the bug
# ... make changes ...

# 3. Commit with conventional commit
git commit -m "fix: correct UTC conversion edge case

Fixes issue where DateTime.Kind was not preserved
when converting from local to UTC time.

BREAKING CHANGE: none
Closes #1234"

# 4. Update version to 2.1.1
# Edit Company.Common.csproj or Directory.Build.props

# 5. Create pull request and merge to main
# 6. Tag the release
git tag -a v2.1.1 -m "Hotfix: UTC conversion fix"
git push origin v2.1.1

Impact Analysis:

Company.Common: 2.1.0 → 2.1.1 (patch)
├── Company.Messaging: 1.8.3 (no change needed - accepts [2.1.0, 3.0.0))
│   └── Company.Contracts: 3.4.1 (no change needed)
└── Services automatically get fix on next build

Services using Company.Common will automatically receive the patch because:

Version range [2.1.0, 3.0.0) includes 2.1.1
NuGet restore pulls the latest compatible version
No breaking changes in patch releases

GitVersion Configuration

Automate versioning with GitVersion:

# GitVersion.yml
mode: ContinuousDelivery
assembly-versioning-scheme: MajorMinorPatch
tag-prefix: 'v'
continuous-delivery-fallback-tag: ci

branches:
  main:
    regex: ^main$
    mode: ContinuousDelivery
    tag: ''
    increment: Minor
    prevent-increment-of-merged-branch-version: true
    track-merge-target: false

  hotfix:
    regex: ^hotfix?[/-]
    mode: ContinuousDelivery
    tag: hotfix
    increment: Patch

  feature:
    regex: ^features?[/-]
    mode: ContinuousDelivery
    tag: feature
    increment: Minor

  release:
    regex: ^releases?[/-]
    mode: ContinuousDelivery
    tag: ''
    increment: Patch

  pull-request:
    regex: ^(pull|pull\-requests|pr)[/-]
    mode: ContinuousDelivery
    tag: pr
    increment: Inherit

CI/CD Pipeline with Azure DevOps

Build and Pack Pipeline

# azure-pipelines-pack.yml
trigger:
  branches:
    include:
    - main
    - release/*
    - hotfix/*
  paths:
    include:
    - 'src/Shared/**'
    - 'azure-pipelines-pack.yml'

pool:
  vmImage: 'ubuntu-latest'

variables:
  buildConfiguration: 'Release'
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true

stages:
- stage: Build
  jobs:
  - job: BuildAndPack
    steps:
    - checkout: self
      fetchDepth: 0  # Required for GitVersion

    - task: UseDotNet@2
      displayName: 'Install .NET 9 SDK'
      inputs:
        version: '9.0.x'

    - task: GitVersion@5
      displayName: 'Calculate Version'
      inputs:
        runtime: 'core'
        configFilePath: 'GitVersion.yml'

    - script: |
        echo "##vso[build.updatebuildnumber]$(GitVersion.SemVer)"
      displayName: 'Update Build Number'

    - task: DotNetCoreCLI@2
      displayName: 'Restore'
      inputs:
        command: 'restore'
        projects: 'src/Shared/**/*.csproj'

    - task: DotNetCoreCLI@2
      displayName: 'Build'
      inputs:
        command: 'build'
        projects: 'src/Shared/**/*.csproj'
        arguments: '--configuration $(buildConfiguration) --no-restore /p:Version=$(GitVersion.NuGetVersion)'

    - task: DotNetCoreCLI@2
      displayName: 'Run Tests'
      inputs:
        command: 'test'
        projects: 'tests/**/*.Tests.csproj'
        arguments: '--configuration $(buildConfiguration) --no-build --collect:"XPlat Code Coverage"'

    - task: PublishCodeCoverageResults@2
      displayName: 'Publish Code Coverage'
      inputs:
        codeCoverageTool: 'Cobertura'
        summaryFileLocation: '$(Agent.TempDirectory)/**/*cobertura.xml'

    - task: DotNetCoreCLI@2
      displayName: 'Pack NuGet Packages'
      inputs:
        command: 'pack'
        packagesToPack: 'src/Shared/**/*.csproj'
        configuration: $(buildConfiguration)
        nobuild: true
        versioningScheme: 'byEnvVar'
        versionEnvVar: 'GitVersion.NuGetVersion'
        packDirectory: '$(Build.ArtifactStagingDirectory)/packages'

    - task: PublishPipelineArtifact@1
      displayName: 'Publish Artifacts'
      inputs:
        targetPath: '$(Build.ArtifactStagingDirectory)/packages'
        artifact: 'nuget-packages'

- stage: PublishInternal
  dependsOn: Build
  condition: and(succeeded(), or(eq(variables['Build.SourceBranch'], 'refs/heads/main'), startsWith(variables['Build.SourceBranch'], 'refs/heads/release/'), startsWith(variables['Build.SourceBranch'], 'refs/heads/hotfix/')))
  jobs:
  - deployment: PublishToFeed
    environment: 'Internal NuGet Feed'
    strategy:
      runOnce:
        deploy:
          steps:
          - download: current
            artifact: 'nuget-packages'

          - task: NuGetCommand@2
            displayName: 'Push to Azure Artifacts'
            inputs:
              command: 'push'
              packagesToPush: '$(Pipeline.Workspace)/nuget-packages/**/*.nupkg;!$(Pipeline.Workspace)/nuget-packages/**/*.symbols.nupkg'
              nuGetFeedType: 'internal'
              publishVstsFeed: 'company-shared-libraries'
              allowPackageConflicts: false

Multi-Stage Pipeline with Approval Gates

# azure-pipelines-release.yml
stages:
- stage: Build
  # ... (same as above)

- stage: PublishInternal
  # ... (same as above)

- stage: PublishProduction
  dependsOn: PublishInternal
  condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/release/'))
  jobs:
  - deployment: PublishToNuGetOrg
    environment: 'Production NuGet' # Requires manual approval
    strategy:
      runOnce:
        deploy:
          steps:
          - download: current
            artifact: 'nuget-packages'

          - task: NuGetCommand@2
            displayName: 'Push to NuGet.org'
            inputs:
              command: 'push'
              packagesToPush: '$(Pipeline.Workspace)/nuget-packages/**/*.nupkg;!$(Pipeline.Workspace)/nuget-packages/**/*.symbols.nupkg'
              nuGetFeedType: 'external'
              publishFeedCredentials: 'NuGet.org Service Connection'

Integration with .NET Aspire

Aspire AppHost Configuration

// CompanyPlatform.AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

// Shared infrastructure
var redis = builder.AddRedis("cache");
var serviceBus = builder.AddAzureServiceBus("messaging");
var sql = builder.AddSqlServer("sql")
    .AddDatabase("orderdb");

// Services with shared defaults
var orderService = builder.AddProject<Projects.OrderService>("order-service")
    .WithReference(sql)
    .WithReference(serviceBus)
    .WithReference(redis);

var customerService = builder.AddProject<Projects.CustomerService>("customer-service")
    .WithReference(serviceBus);

var shippingService = builder.AddProject<Projects.ShippingService>("shipping-service")
    .WithReference(serviceBus);

// All services automatically get Company.ServiceDefaults behavior
builder.Build().Run();

Service Implementation

// OrderService/Program.cs
var builder = WebApplication.CreateBuilder(args);

// Apply company defaults (includes observability, resilience, health checks)
builder.AddCompanyServiceDefaults();

// Add Aspire components
builder.AddServiceDefaults();
builder.AddSqlServerDbContext<OrderDbContext>("orderdb");
builder.AddAzureServiceBusClient("messaging");

// Service-specific registrations
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();

app.MapCompanyDefaultEndpoints();
app.MapOrderEndpoints();

app.Run();

Package Consumption Best Practices

Version Pinning Strategy

<!-- For stable production services -->
<ItemGroup>
  <!-- Pin to exact versions for predictability -->
  <PackageReference Include="Company.Common" Version="2.1.0" />
  <PackageReference Include="Company.Messaging" Version="1.8.3" />
</ItemGroup>

<!-- For active development -->
<ItemGroup>
  <!-- Use ranges to get patches automatically -->
  <PackageReference Include="Company.Common" Version="[2.1.0,2.2.0)" />
  <PackageReference Include="Company.Messaging" Version="[1.8.0,2.0.0)" />
</ItemGroup>

Dependency Resolution

Configure NuGet to prioritize your internal feed:

<!-- nuget.config -->
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <!-- Company internal feed first -->
    <add key="Company" value="https://pkgs.dev.azure.com/yourorg/_packaging/company-shared-libraries/nuget/v3/index.json" />
    <!-- Public NuGet.org second -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="Company">
      <package pattern="Company.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Monitoring and Observability

Package Health Dashboard

Track package adoption and health:

// Custom metrics for package usage
public class PackageHealthMetrics
{
    private readonly Counter<int> _packageDownloads;
    private readonly Histogram<double> _buildDuration;

    public PackageHealthMetrics(IMeterFactory meterFactory)
    {
        var meter = meterFactory.Create("Company.Packages");

        _packageDownloads = meter.CreateCounter<int>(
            "package.downloads",
            description: "Number of package downloads");

        _buildDuration = meter.CreateHistogram<double>(
            "package.build.duration",
            unit: "s",
            description: "Package build duration");
    }

    public void RecordDownload(string packageId, string version)
    {
        _packageDownloads.Add(1, 
            new KeyValuePair<string, object?>("package.id", packageId),
            new KeyValuePair<string, object?>("package.version", version));
    }
}

Azure Monitor Integration

// Application Insights for package telemetry
builder.Services.AddApplicationInsightsTelemetry(options =>
{
    options.ConnectionString = builder.Configuration
        .GetConnectionString("ApplicationInsights");
});

// Custom telemetry for package health
builder.Services.AddSingleton<ITelemetryInitializer, PackageTelemetryInitializer>();

public class PackageTelemetryInitializer : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        if (telemetry is ISupportProperties propertyTelemetry)
        {
            propertyTelemetry.Properties["SharedLibVersion.Common"] = 
                typeof(Company.Common.Extensions.DateTimeExtensions)
                    .Assembly.GetName().Version?.ToString() ?? "unknown";
        }
    }
}

Breaking Changes Management

Communicating Breaking Changes

Use attributes and XML documentation to signal changes:

// Company.Common
namespace Company.Common.Extensions;

public static class DateTimeExtensions
{
    // Deprecated method - will be removed in v3.0.0
    [Obsolete("Use ToUtc() instead. This method will be removed in v3.0.0", false)]
    [EditorBrowsable(EditorBrowsableState.Never)]
    public static DateTime ConvertToUtc(this DateTime dateTime)
        => dateTime.ToUtc();

    /// <summary>
    /// Converts a DateTime to UTC, preserving the underlying instant in time.
    /// </summary>
    /// <param name="dateTime">The date and time to convert.</param>
    /// <returns>The date and time in UTC.</returns>
    /// <remarks>
    /// Added in v2.1.0. This replaces the deprecated ConvertToUtc method.
    /// </remarks>
    public static DateTime ToUtc(this DateTime dateTime)
    {
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }
}

Migration Guides

Include migration documentation in your packages:

<!-- MIGRATION-v3.0.md -->
# Migration Guide: v2.x to v3.0

## Breaking Changes

### Company.Common

**Removed: `DateTimeExtensions.ConvertToUtc()`**
- **Replacement:** Use `DateTimeExtensions.ToUtc()`
- **Migration:**

csharp
// Before (v2.x)
var utcTime = localTime.ConvertToUtc();

// After (v3.0)
var utcTime = localTime.ToUtc();


**Changed: `Result<T>` now uses `required` properties**
- **Impact:** Cannot use object initializer without all required properties
- **Migration:**

csharp
// Before (v2.x)
var result = new Result { Value = "test", IsSuccess = true };

// After (v3.0) - use factory methods
var result = Result.Success("test");


### Company.Messaging

**Removed: `EventBase.Timestamp`**
- **Replacement:** Use `EventBase.OccurredAtUtc`
- **Reason:** Improved clarity and UTC enforcement

## New Features

### Company.Common
- Added `StringExtensions.IsNullOrWhiteSpace()` with null checking
- Added `Result<T>.Map()` and `Result<T>.Bind()` for functional composition

### Company.Observability
- Full .NET 9 metrics API support
- Enhanced OpenTelemetry integration
- Azure Monitor auto-configuration

Advanced Patterns

Feature Flags in Shared Libraries

Enable gradual rollout of changes:

// Company.Common - Feature flag support
namespace Company.Common.Features;

public interface IFeatureManager
{
    Task<bool> IsEnabledAsync(string featureName);
    Task<T> GetVariantAsync<T>(string featureName, T defaultValue);
}

public static class FeatureExtensions
{
    public static IServiceCollection AddCompanyFeatureManagement(
        this IServiceCollection services)
    {
        services.AddFeatureManagement()
            .AddFeatureFilter<PercentageFilter>()
            .AddFeatureFilter<TargetingFilter>();

        return services;
    }
}

// Usage in shared library
public static class DateTimeExtensions
{
    public static async Task<DateTime> ToUtcAsync(
        this DateTime dateTime,
        IFeatureManager? featureManager = null)
    {
        // New implementation behind feature flag
        if (featureManager != null && 
            await featureManager.IsEnabledAsync("UseEnhancedUtcConversion"))
        {
            return EnhancedToUtc(dateTime);
        }

        // Legacy implementation
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }

    private static DateTime EnhancedToUtc(DateTime dateTime)
    {
        // New implementation with additional validations
        // ...
    }
}

Multi-Targeting for Backward Compatibility

Support multiple .NET versions when needed:

<!-- Company.Common.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>

  <!-- Conditional compilation -->
  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
    <PackageReference Include="System.Text.Json" Version="8.0.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
    <PackageReference Include="System.Text.Json" Version="9.0.0" />
  </ItemGroup>
</Project>

// Conditional compilation in code
namespace Company.Common.Serialization;

public static class JsonExtensions
{
#if NET9_0_OR_GREATER
    // Use new .NET 9 features
    public static T? Deserialize<T>(this string json, JsonSerializerOptions? options = null)
    {
        return JsonSerializer.Deserialize<T>(json, options ?? JsonSerializerOptions.Web);
    }
#else
    // Fallback for .NET 8
    public static T? Deserialize<T>(this string json, JsonSerializerOptions? options = null)
    {
        return JsonSerializer.Deserialize<T>(json, options ?? new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        });
    }
#endif
}

Testing Shared Libraries

Unit Testing Strategy

// Company.Common.Tests/Extensions/DateTimeExtensionsTests.cs
namespace Company.Common.Tests.Extensions;

public class DateTimeExtensionsTests
{
    [Theory]
    [InlineData("2025-01-15T10:30:00Z", DateTimeKind.Utc)]
    [InlineData("2025-01-15T10:30:00", DateTimeKind.Unspecified)]
    [InlineData("2025-01-15T10:30:00", DateTimeKind.Local)]
    public void ToUtc_ShouldReturnUtcDateTime(string dateTimeString, DateTimeKind kind)
    {
        // Arrange
        var dateTime = DateTime.Parse(dateTimeString);
        dateTime = DateTime.SpecifyKind(dateTime, kind);

        // Act
        var result = dateTime.ToUtc();

        // Assert
        result.Kind.Should().Be(DateTimeKind.Utc);
    }

    [Fact]
    public void ToUtc_WhenAlreadyUtc_ShouldReturnSameInstance()
    {
        // Arrange
        var utcTime = DateTime.UtcNow;

        // Act
        var result = utcTime.ToUtc();

        // Assert
        result.Should().BeSameAs(utcTime);
    }
}

Integration Testing with Test Containers

// Company.Messaging.Tests/ServiceBusIntegrationTests.cs
using Testcontainers.Azurite;

public class ServiceBusIntegrationTests : IAsyncLifetime
{
    private AzuriteContainer _azurite = null!;
    private IServiceProvider _services = null!;

    public async Task InitializeAsync()
    {
        _azurite = new AzuriteBuilder()
            .WithImage("mcr.microsoft.com/azure-storage/azurite:latest")
            .Build();

        await _azurite.StartAsync();

        var services = new ServiceCollection();
        services.AddAzureClients(builder =>
        {
            builder.AddServiceBusClient(_azurite.GetConnectionString());
        });

        _services = services.BuildServiceProvider();
    }

    [Fact]
    public async Task PublishEvent_ShouldSucceed()
    {
        // Arrange
        var publisher = _services.GetRequiredService<IEventPublisher>();
        var testEvent = new OrderCreatedEvent(Guid.NewGuid(), Guid.NewGuid(), 100m, DateTime.UtcNow);

        // Act
        await publisher.PublishAsync(testEvent);

        // Assert - event should be in queue
        // ...
    }

    public async Task DisposeAsync()
    {
        await _azurite.DisposeAsync();
    }
}

Contract Testing

Ensure backward compatibility of contracts:

// Company.Contracts.Tests/OrderCreatedEventTests.cs
public class OrderCreatedEventTests
{
    [Fact]
    public void OrderCreatedEvent_ShouldDeserializeFromV1Schema()
    {
        // Arrange - JSON from v1.0 contract
        var v1Json = """
        {
            "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "customerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "totalAmount": 299.99,
            "createdAtUtc": "2025-01-15T10:30:00Z"
        }
        """;

        // Act
        var evt = JsonSerializer.Deserialize<OrderCreatedEvent>(v1Json);

        // Assert
        evt.Should().NotBeNull();
        evt!.OrderId.Should().Be(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));
        evt.Currency.Should().Be("USD"); // Default value added in v1.1
    }

    [Fact]
    public void OrderCreatedEvent_ShouldSerializeWithAllFields()
    {
        // Arrange
        var evt = new OrderCreatedEvent(
            Guid.NewGuid(),
            Guid.NewGuid(),
            299.99m,
            DateTime.UtcNow,
            "EUR");

        // Act
        var json = JsonSerializer.Serialize(evt);
        var deserialized = JsonSerializer.Deserialize<OrderCreatedEvent>(json);

        // Assert
        deserialized.Should().BeEquivalentTo(evt);
    }
}

Security Considerations

Package Signing

Sign your NuGet packages for authenticity:

<!-- Directory.Build.props -->
<PropertyGroup>
  <SignAssembly>true</SignAssembly>
  <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)company-key.snk</AssemblyOriginatorKeyFile>

  <!-- NuGet package signing -->
  <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
</PropertyGroup>

# In Azure Pipeline
- task: NuGetCommand@2
  displayName: 'Sign NuGet Packages'
  inputs:
    command: custom
    arguments: 'sign $(Build.ArtifactStagingDirectory)/**/*.nupkg -CertificatePath $(SigningCertificate.secureFilePath) -CertificatePassword $(CertPassword) -Timestamper http://timestamp.digicert.com'

Dependency Scanning

Integrate security scanning into your pipeline:

# azure-pipelines-security.yml
- task: DotNetCoreCLI@2
  displayName: 'Restore with Dependency Check'
  inputs:
    command: 'restore'
    projects: '**/*.csproj'

- task: ComponentGovernanceComponentDetection@0
  displayName: 'Component Detection'
  inputs:
    scanType: 'Register'
    verbosity: 'Verbose'
    alertWarningLevel: 'High'

- script: |
    dotnet list package --vulnerable --include-transitive
  displayName: 'Check for Vulnerable Dependencies'

- script: |
    dotnet list package --deprecated
  displayName: 'Check for Deprecated Packages'

Secrets Management in Shared Libraries

Never hardcode secrets - use configuration:

// Company.Common - Secure configuration
namespace Company.Common.Configuration;

public static class SecureConfigurationExtensions
{
    public static IConfigurationBuilder AddCompanySecrets(
        this IConfigurationBuilder builder,
        IHostEnvironment environment)
    {
        if (environment.IsDevelopment())
        {
            builder.AddUserSecrets<Program>();
        }
        else
        {
            // Azure Key Vault in production
            var config = builder.Build();
            var keyVaultUri = config["KeyVault:Uri"];

            if (!string.IsNullOrEmpty(keyVaultUri))
            {
                builder.AddAzureKeyVault(
                    new Uri(keyVaultUri),
                    new DefaultAzureCredential());
            }
        }

        return builder;
    }
}

Documentation and Discoverability

XML Documentation

Comprehensive documentation improves adoption:

/// <summary>
/// Provides extension methods for <see cref="DateTime"/> operations with UTC handling.
/// </summary>
/// <remarks>
/// This class contains utility methods for working with dates and times, with a focus
/// on ensuring consistent UTC time handling across microservices.
/// 
/// <para>
/// <strong>Version History:</strong>
/// </para>
/// <list type="bullet">
/// <item><description>v2.1.0 - Added ToUtc() method</description></item>
/// <item><description>v2.0.0 - Initial release</description></item>
/// </list>
/// </remarks>
/// <example>
/// <code>
/// var localTime = DateTime.Now;
/// var utcTime = localTime.ToUtc();
/// Console.WriteLine($"UTC: {utcTime:u}");
/// </code>
/// </example>
public static class DateTimeExtensions
{
    /// <summary>
    /// Converts a <see cref="DateTime"/> to UTC, preserving the underlying instant in time.
    /// </summary>
    /// <param name="dateTime">The date and time to convert.</param>
    /// <returns>
    /// A <see cref="DateTime"/> with <see cref="DateTimeKind.Utc"/>.
    /// If the input is already UTC, returns the same instance.
    /// </returns>
    /// <exception cref="ArgumentException">
    /// Thrown when the DateTime represents an invalid time (e.g., during DST transition).
    /// </exception>
    /// <example>
    /// <code>
    /// var localTime = new DateTime(2025, 1, 15, 10, 30, 0, DateTimeKind.Local);
    /// var utcTime = localTime.ToUtc();
    /// // utcTime.Kind == DateTimeKind.Utc
    /// </code>
    /// </example>
    public static DateTime ToUtc(this DateTime dateTime)
    {
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }
}

README.md for Each Package

<!-- Company.Common/README.md -->
# Company.Common

[![NuGet Version](https://img.shields.io/nuget/v/Company.Common.svg)](https://www.nuget.org/packages/Company.Common/)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Company.Common.svg)](https://www.nuget.org/packages/Company.Common/)

Common utilities and extensions for Company microservices architecture.

## Installation

bash
dotnet add package Company.Common


## Features

- **DateTime Extensions**: UTC conversion utilities
- **String Extensions**: Null checking helpers
- **Result Pattern**: Functional error handling
- **Performance**: Zero-allocation where possible

## Quick Start

csharp
using Company.Common.Extensions;

// DateTime utilities
var utcTime = DateTime.Now.ToUtc();
var dateOnly = utcTime.ToDateOnly();

// String helpers
if (!input.IsNullOrWhiteSpace())
{
// Process input
}

// Result pattern
var result = Result.Success(42);
if (result.IsSuccess)
{
Console.WriteLine(result.Value);
}


## Documentation

Full documentation available at [nova-globen.se](https://nova-globen.se)

## Version Compatibility

| Company.Common | .NET Version | Support |
|----------------|--------------|---------|
| 2.x            | .NET 9       | ✅ Active |
| 1.x            | .NET 8       | ⚠️ Maintenance |

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md)

## License

MIT License - see [LICENSE](../../LICENSE)

csharp

Performance Considerations

Benchmarking Shared Libraries

Use BenchmarkDotNet to validate performance:

// Company.Common.Benchmarks/DateTimeExtensionsBenchmarks.cs
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
public class DateTimeExtensionsBenchmarks
{
    private DateTime _localTime;
    private DateTime _utcTime;

    [GlobalSetup]
    public void Setup()
    {
        _localTime = DateTime.Now;
        _utcTime = DateTime.UtcNow;
    }

    [Benchmark(Baseline = true)]
    public DateTime ToUniversalTime_Baseline()
    {
        return _localTime.ToUniversalTime();
    }

    [Benchmark]
    public DateTime ToUtc_Extension()
    {
        return _localTime.ToUtc();
    }

    [Benchmark]
    public DateTime ToUtc_AlreadyUtc()
    {
        return _utcTime.ToUtc(); // Should be no-op
    }
}

// Results tracking
/*
| Method                 | Mean      | Error    | StdDev   | Gen0   | Allocated |
|----------------------- |----------:|---------:|---------:|-------:|----------:|
| ToUniversalTime_Base   | 45.23 ns  | 0.234 ns | 0.218 ns | -      | -         |
| ToUtc_Extension        | 45.18 ns  | 0.198 ns | 0.185 ns | -      | -         |
| ToUtc_AlreadyUtc       |  2.34 ns  | 0.012 ns | 0.011 ns | -      | -         |
*/

Optimizing Package Size

<!-- Reduce package size -->
<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <TrimMode>link</TrimMode>

  <!-- Debug symbols in separate package -->
  <DebugType>portable</DebugType>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>

  <!-- Exclude unnecessary files -->
  <NoWarn>$(NoWarn);NU5128</NoWarn>
  <ContentTargetFolders>content</ContentTargetFolders>
</PropertyGroup>

<ItemGroup>
  <None Remove="**/*.Development.json" />
  <None Remove="**/*.local.json" />
</ItemGroup>

Governance and Ownership

Package Ownership Model

Define clear ownership:

# CODEOWNERS
# Shared libraries ownership

src/Shared/Company.Common/**           @platform-team @architecture-team
src/Shared/Company.Messaging/**        @platform-team @messaging-team
src/Shared/Company.Contracts/**        @api-team @architecture-team
src/Shared/Company.Observability/**    @platform-team @sre-team
src/Shared/Company.ServiceDefaults/**  @platform-team @devex-team

# Require approval from platform team for all shared library changes
src/Shared/**                          @platform-team

Change Request Process

<!-- .github/PULL_REQUEST_TEMPLATE.md -->
## Shared Library Change Request

### Package(s) Affected
- [ ] Company.Common
- [ ] Company.Messaging
- [ ] Company.Contracts
- [ ] Company.Observability
- [ ] Company.ServiceDefaults

### Change Type
- [ ] New Feature
- [ ] Bug Fix
- [ ] Breaking Change
- [ ] Performance Improvement
- [ ] Documentation

### Version Impact
- Current Version: x.y.z
- Proposed Version: x.y.z
- Justification: [Major/Minor/Patch]

### Breaking Changes
<!-- If yes, describe migration path -->
- [ ] No breaking changes
- [ ] Breaking changes documented in MIGRATION.md

### Impact Analysis
- Estimated services affected: X
- Migration effort: [Low/Medium/High]
- Rollout strategy: [describe]

### Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Performance benchmarks run
- [ ] Backward compatibility verified

### Documentation
- [ ] XML documentation updated
- [ ] README.md updated
- [ ] Migration guide created (if breaking)
- [ ] Changelog updated

### Checklist
- [ ] Code follows company standards
- [ ] No secrets or sensitive data
- [ ] Semantic versioning followed
- [ ] Release notes prepared

Summary and Best Practices

Key Takeaways

Keep shared libraries focused on infrastructure
- ✅ Logging, extensions, messaging abstractions
- ❌ Domain models, business logic
Each microservice owns its domain model
- Services communicate via contracts (DTOs/events)
- No shared domain entities across services
Use semantic versioning rigorously
- Major: Breaking changes
- Minor: New features (backward compatible)
- Patch: Bug fixes
Leverage .NET 9 features
- Enhanced metrics and observability
- Improved performance
- Better tooling support
Integrate with .NET Aspire
- Standardized service defaults
- Simplified local development
- Built-in observability
Automate everything
- CI/CD for package publishing
- Automated versioning with GitVersion
- Security scanning in pipelines
Document thoroughly
- XML documentation
- README files
- Migration guides for breaking changes
Monitor and measure
- Package download metrics
- Performance benchmarks
- Dependency health

Anti-Patterns to Avoid

❌ Don't do this:

Sharing domain entities across services
Including business logic in shared libraries
Creating "God packages" with everything
Breaking semantic versioning rules
Hardcoding configuration or secrets
Publishing without tests
Ignoring backward compatibility
Skipping documentation

✅ Do this instead:

Keep packages focused and cohesive
Share only contracts and infrastructure
Follow semantic versioning strictly
Automate testing and publishing
Document changes and migration paths
Monitor package health and adoption

Additional Resources

This guide is maintained by the Platform Engineering team. For questions or contributions, contact desmati@gmail.com or visit nova-globen.se for more architectural guidance.

Service Mesh in .NET core

Hossein Esmati — Fri, 26 Jun 2026 12:30:19 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

Key Benefits

Traffic Management: Load balancing, routing, and traffic splitting for canary deployments
Security: Mutual TLS (mTLS) encryption, authentication, and authorization between services
Observability: Distributed tracing, metrics, and logging for service interactions
Resilience: Automatic retries, circuit breaking, and timeout policies

Popular Service Mesh Options

Istio

Full-featured, Kubernetes-native service mesh offering comprehensive traffic management, security policies, and observability. Best for complex enterprise environments requiring fine-grained control.

Linkerd

Lightweight and simpler alternative focused on ease of use and minimal resource overhead. Ideal for teams wanting service mesh benefits without operational complexity.

Dapr (Distributed Application Runtime)

Multi-runtime, cloud-agnostic framework that works beyond Kubernetes across VMs, edge, and cloud environments. Provides building blocks for microservices including service invocation, pub/sub, state management, and more.

.NET Aspire: Cloud-Native Orchestration

.NET Aspire is Microsoft's opinionated stack for building observable, production-ready cloud-native applications with .NET 9. While not a traditional service mesh, Aspire provides service discovery, orchestration, and observability features that complement or serve as alternatives to service meshes in certain scenarios.

Key Aspire Features:

Automatic service discovery and health checks
Built-in OpenTelemetry integration for distributed tracing
Local development orchestration with production-ready patterns
Azure integration for seamless cloud deployment

// .NET Aspire App Host (Program.cs)
var builder = DistributedApplication.CreateBuilder(args);

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

var customerService = builder.AddProject<Projects.CustomerService>("customer-service")
    .WithReference(cache);

var orderService = builder.AddProject<Projects.OrderService>("order-service")
    .WithReference(cache)
    .WithReference(messaging)
    .WithReference(customerService); // Automatic service discovery

builder.Build().Run();

Dapr with .NET 9 and C# 13

Dapr integrates seamlessly with .NET 9, leveraging modern C# features and Azure services.

Service Invocation and Pub/Sub

using Dapr.Client;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

// Add Dapr services
builder.Services.AddControllers().AddDapr();
builder.Services.AddDaprClient();

var app = builder.Build();

app.MapControllers();
app.MapSubscribeHandler(); // Dapr pub/sub subscriptions

app.Run();

[ApiController]
[Route("api/[controller]")]
public class OrderController(DaprClient daprClient, IOrderService orderService) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        // Save order using primary constructor parameter
        var order = await orderService.CreateAsync(request);

        // Publish event via Dapr pub/sub to Azure Service Bus
        await daprClient.PublishEventAsync(
            "servicebus-pubsub",
            "order-events",
            new OrderCreatedEvent 
            { 
                OrderId = order.Id,
                CustomerId = request.CustomerId,
                CreatedAt = DateTime.UtcNow
            });

        // Invoke customer service with resilience (automatic retries)
        var customer = await daprClient.InvokeMethodAsync<Customer>(
            HttpMethod.Get,
            "customer-service",
            $"api/customers/{request.CustomerId}");

        return Ok(new { order, customer });
    }

    // Dapr pub/sub subscription
    [Topic("servicebus-pubsub", "payment-events")]
    [HttpPost("payment-processed")]
    public async Task<IActionResult> HandlePaymentProcessed(PaymentProcessedEvent @event)
    {
        await orderService.UpdatePaymentStatusAsync(@event.OrderId, @event.Status);
        return Ok();
    }
}

// Event records using C# 13 features
public record OrderCreatedEvent
{
    required public string OrderId { get; init; }
    required public string CustomerId { get; init; }
    required public DateTime CreatedAt { get; init; }
}

public record PaymentProcessedEvent(string OrderId, string Status);

State Management with Azure Cosmos DB

public class OrderService(DaprClient daprClient)
{
    private const string StateStoreName = "cosmosdb-state";

    public async Task<Order> CreateAsync(CreateOrderRequest request)
    {
        var order = new Order
        {
            Id = Guid.NewGuid().ToString(),
            CustomerId = request.CustomerId,
            Items = request.Items,
            Status = OrderStatus.Pending
        };

        // Save to Cosmos DB via Dapr state management
        await daprClient.SaveStateAsync(StateStoreName, order.Id, order);

        return order;
    }

    public async Task<Order?> GetAsync(string orderId)
    {
        return await daprClient.GetStateAsync<Order>(StateStoreName, orderId);
    }
}

Azure Integration with Dapr Components

Dapr Component for Azure Service Bus (components/servicebus-pubsub.yaml):

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.topics
  version: v1
  metadata:
  - name: connectionString
    secretKeyRef:
      name: azure-servicebus-connection
  - name: consumerID
    value: "order-service"

Dapr Component for Azure Cosmos DB (components/cosmosdb-state.yaml):

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: cosmosdb-state
spec:
  type: state.azure.cosmosdb
  version: v1
  metadata:
  - name: url
    value: "https://your-account.documents.azure.com:443/"
  - name: masterKey
    secretKeyRef:
      name: cosmosdb-key
  - name: database
    value: "orders-db"
  - name: collection
    value: "orders"

Choosing the Right Approach

Use .NET Aspire for cloud-native .NET applications requiring orchestration, observability, and Azure integration with minimal setup
Use Dapr for polyglot microservices, multi-cloud scenarios, or when you need portable building blocks across different hosting environments
Use Traditional Service Meshes (Istio/Linkerd) for Kubernetes-native applications requiring advanced traffic management and security policies at the infrastructure level

For comprehensive microservices patterns and best practices, visit nova-globen.se.

Additional Resources

Ready to modernize your microservices architecture? Explore more patterns and tutorials at nova-globen.se.

Service Discovery in Modern .NET Applications and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:25:09 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

Service Discovery in Kubernetes

How Kubernetes DNS Works

Kubernetes automatically creates DNS entries for services, enabling simple name-based discovery. A service named order-service in the production namespace becomes accessible at order-service.production.svc.cluster.local. For services within the same namespace, you can use the short name order-service.

Service Definition:

apiVersion: v1
kind: Service
metadata:
  name: order-service
  namespace: production
  labels:
    app: order-service
    version: v1
spec:
  selector:
    app: order-service
  ports:
  - name: http
    protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

Native Service Discovery in .NET 9

.NET 9 introduces enhanced service discovery capabilities with improved configuration and resilience features.

Basic Configuration:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Add service discovery with .NET 9 enhancements
builder.Services.AddServiceDiscovery();

// Configure HTTP client with service discovery
builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    // Use service name - discovery resolves to actual endpoint
    client.BaseAddress = new Uri("http://order-service");
})
.AddServiceDiscovery()
.AddStandardResilienceHandler(); // .NET 9 resilience patterns

var app = builder.Build();

Advanced Configuration with appsettings.json:

{
  "ServiceDiscovery": {
    "Providers": {
      "Kubernetes": {
        "Namespace": "production",
        "RefreshPeriod": "00:01:00"
      }
    },
    "Services": {
      "order-service": {
        "Scheme": "https",
        "EndpointNames": ["http", "https"],
        "HealthCheckPath": "/health"
      },
      "payment-service": {
        "Scheme": "http",
        "AllowAllHosts": false
      }
    },
    "AllowAllHosts": true,
    "AllowedHosts": ["*.svc.cluster.local"]
  }
}

Service-to-Service Communication Patterns

Using Typed HTTP Clients:

public interface IOrderServiceClient
{
    Task<Order> GetOrderAsync(Guid orderId, CancellationToken cancellationToken = default);
    Task<IEnumerable<Order>> GetOrdersByCustomerAsync(Guid customerId, CancellationToken cancellationToken = default);
}

public class OrderServiceClient : IOrderServiceClient
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<OrderServiceClient> _logger;

    public OrderServiceClient(HttpClient httpClient, ILogger<OrderServiceClient> logger)
    {
        _httpClient = httpClient;
        _logger = logger;
    }

    public async Task<Order> GetOrderAsync(Guid orderId, CancellationToken cancellationToken = default)
    {
        try
        {
            var response = await _httpClient.GetFromJsonAsync<Order>(
                $"api/orders/{orderId}", 
                cancellationToken);

            return response ?? throw new OrderNotFoundException(orderId);
        }
        catch (HttpRequestException ex)
        {
            _logger.LogError(ex, "Failed to retrieve order {OrderId}", orderId);
            throw;
        }
    }

    public async Task<IEnumerable<Order>> GetOrdersByCustomerAsync(
        Guid customerId, 
        CancellationToken cancellationToken = default)
    {
        return await _httpClient.GetFromJsonAsync<IEnumerable<Order>>(
            $"api/orders/customer/{customerId}", 
            cancellationToken) ?? [];
    }
}

Service Registration with Resilience:

builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    client.BaseAddress = new Uri("http://order-service");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddServiceDiscovery()
.AddStandardResilienceHandler(options =>
{
    // Configure circuit breaker
    options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(10);
    options.CircuitBreaker.FailureRatio = 0.5;
    options.CircuitBreaker.MinimumThroughput = 10;

    // Configure retry policy
    options.Retry.MaxRetryAttempts = 3;
    options.Retry.BackoffType = Polly.DelayBackoffType.Exponential;

    // Configure timeout
    options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(30);
});

Service Discovery in Azure Container Apps

Azure Container Apps provides built-in service discovery within the same environment, eliminating the need for manual endpoint configuration.

Environment Variables Approach

Container App Configuration:

{
  "properties": {
    "environmentId": "/subscriptions/.../containerappsenvironments/production-env",
    "configuration": {
      "ingress": {
        "external": false,
        "targetPort": 8080,
        "transport": "http",
        "allowInsecure": false
      }
    },
    "template": {
      "containers": [{
        "name": "api-service",
        "image": "myregistry.azurecr.io/api-service:latest",
        "env": [{
          "name": "OrderService__Url",
          "value": "https://order-service.internal.<environment-unique-id>.azurecontainerapps.io"
        },
        {
          "name": "ASPNETCORE_ENVIRONMENT",
          "value": "Production"
        }],
        "resources": {
          "cpu": 0.5,
          "memory": "1Gi"
        }
      }]
    }
  }
}

Consuming in .NET:

services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    var orderServiceUrl = configuration["OrderService:Url"] 
        ?? throw new InvalidOperationException("OrderService URL not configured");
    client.BaseAddress = new Uri(orderServiceUrl);
});

Native Service Discovery in Container Apps

Azure Container Apps now supports simplified service discovery using service names directly.

var builder = WebApplication.CreateBuilder(args);

// Add Azure Container Apps service discovery
builder.Services.AddServiceDiscovery();

builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    // Reference by Container App name within the same environment
    client.BaseAddress = new Uri("http://order-service");
})
.AddServiceDiscovery()
.AddStandardResilienceHandler();

// For external Container Apps (different environment)
builder.Services.AddHttpClient<IPaymentServiceClient, PaymentServiceClient>(client =>
{
    client.BaseAddress = new Uri("https://payment-service.politeocean-12345678.westeurope.azurecontainerapps.io");
})
.AddStandardResilienceHandler();

Dapr Integration for Service Invocation

Dapr (Distributed Application Runtime) provides a robust service invocation model with built-in retry, tracing, and security.

Dapr Configuration:

var builder = WebApplication.CreateBuilder(args);

// Add Dapr services
builder.Services.AddDaprClient();
builder.Services.AddControllers().AddDapr();

var app = builder.Build();
app.UseRouting();
app.UseCloudEvents(); // Enable CloudEvents for pub/sub
app.MapSubscribeHandler(); // Map Dapr subscription endpoint
app.MapControllers();

Service Invocation with Dapr:

public class OrderController : ControllerBase
{
    private readonly DaprClient _daprClient;
    private readonly ILogger<OrderController> _logger;

    public OrderController(DaprClient daprClient, ILogger<OrderController> logger)
    {
        _daprClient = daprClient;
        _logger = logger;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetOrder(Guid id)
    {
        try
        {
            // Invoke customer service via Dapr sidecar
            var customer = await _daprClient.InvokeMethodAsync<Customer>(
                HttpMethod.Get,
                "customer-service", // Dapr App ID
                $"api/customers/{id}");

            if (customer is null)
            {
                return NotFound();
            }

            return Ok(customer);
        }
        catch (DaprException ex)
        {
            _logger.LogError(ex, "Failed to invoke customer service for customer {CustomerId}", id);
            return StatusCode(503, "Service temporarily unavailable");
        }
    }

    [HttpPost]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // Invoke with request/response
        var inventoryCheck = await _daprClient.InvokeMethodAsync<InventoryCheckRequest, InventoryCheckResponse>(
            HttpMethod.Post,
            "inventory-service",
            "api/inventory/check",
            new InventoryCheckRequest 
            { 
                ProductId = request.ProductId, 
                Quantity = request.Quantity 
            });

        if (!inventoryCheck.IsAvailable)
        {
            return BadRequest("Insufficient inventory");
        }

        // Process order creation...
        return CreatedAtAction(nameof(GetOrder), new { id = Guid.NewGuid() }, null);
    }
}

Dapr Component Configuration for Container Apps:

# dapr-components.yaml
componentType: state.azure.cosmosdb
version: v1
metadata:
- name: url
  value: "https://mycosmosdb.documents.azure.com:443/"
- name: masterKey
  secretRef: cosmosdb-key
- name: database
  value: "ordersdb"
- name: collection
  value: "orders"
scopes:
- order-service

API Gateway and Ingress Patterns

What is an API Gateway?

An API gateway serves as a single entry point for client requests, providing:

Request routing to appropriate microservices
Authentication and authorization enforcement
Rate limiting and throttling to prevent abuse
Request/response transformation for protocol translation
Caching to improve performance
Load balancing across service instances
Monitoring and analytics for observability

Azure API Management

Azure API Management provides enterprise-grade API gateway capabilities with comprehensive policy support.

Read Configure ingress for an Azure Container Apps environment

Policy Configuration:

<policies>
    <inbound>
        <base />
        <!-- Rate limiting -->
        <rate-limit-by-key calls="100" 
                           renewal-period="60" 
                           counter-key="@(context.Request.IpAddress)" />

        <!-- JWT validation -->
        <validate-jwt header-name="Authorization" 
                      failed-validation-httpcode="401" 
                      failed-validation-error-message="Unauthorized">
            <openid-config url="https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration" />
            <required-claims>
                <claim name="roles" match="any">
                    <value>api.read</value>
                    <value>api.write</value>
                </claim>
            </required-claims>
        </validate-jwt>

        <!-- Dynamic backend routing -->
        <choose>
            <when condition="@(context.Request.Url.Path.StartsWith("/api/orders"))">
                <set-backend-service base-url="http://order-service.production.svc.cluster.local" />
            </when>
            <when condition="@(context.Request.Url.Path.StartsWith("/api/customers"))">
                <set-backend-service base-url="http://customer-service.production.svc.cluster.local" />
            </when>
            <otherwise>
                <return-response>
                    <set-status code="404" reason="Not Found" />
                </return-response>
            </otherwise>
        </choose>

        <!-- Add correlation ID -->
        <set-header name="X-Correlation-ID" exists-action="skip">
            <value>@(Guid.NewGuid().ToString())</value>
        </set-header>
    </inbound>
    <backend>
        <base />
        <retry condition="@(context.Response.StatusCode >= 500)" 
               count="3" 
               interval="2" 
               delta="1" 
               first-fast-retry="true" />
    </backend>
    <outbound>
        <base />
        <!-- Remove internal headers -->
        <set-header name="X-Powered-By" exists-action="delete" />
        <set-header name="X-AspNet-Version" exists-action="delete" />
    </outbound>
    <on-error>
        <base />
        <set-body>@{
            return new JObject(
                new JProperty("error", context.LastError.Message),
                new JProperty("correlationId", context.Request.Headers.GetValueOrDefault("X-Correlation-ID"))
            ).ToString();
        }</set-body>
    </on-error>
</policies>

YARP - .NET Native API Gateway

YARP (Yet Another Reverse Proxy) is a highly performant, .NET-native reverse proxy toolkit ideal for building custom API gateways.

Configuration:

{
  "ReverseProxy": {
    "Routes": {
      "order-route": {
        "ClusterId": "order-cluster",
        "Match": {
          "Path": "/api/orders/{**catch-all}"
        },
        "Transforms": [
          { "PathRemovePrefix": "/api" },
          { "RequestHeader": "X-Forwarded-For", "Append": "{RemoteIpAddress}" },
          { "RequestHeader": "X-Original-Host", "Set": "{OriginalHost}" }
        ],
        "Metadata": {
          "requireAuth": "true"
        }
      },
      "customer-route": {
        "ClusterId": "customer-cluster",
        "Match": {
          "Path": "/api/customers/{**catch-all}"
        },
        "RateLimiterPolicy": "fixed",
        "AuthorizationPolicy": "authenticated"
      },
      "websocket-route": {
        "ClusterId": "notification-cluster",
        "Match": {
          "Path": "/notifications"
        }
      }
    },
    "Clusters": {
      "order-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://order-service",
            "Health": "http://order-service/health"
          }
        },
        "HealthCheck": {
          "Active": {
            "Enabled": true,
            "Interval": "00:00:10",
            "Timeout": "00:00:05",
            "Policy": "ConsecutiveFailures",
            "Path": "/health"
          }
        },
        "LoadBalancingPolicy": "RoundRobin"
      },
      "customer-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://customer-service"
          },
          "destination2": {
            "Address": "http://customer-service-2"
          }
        }
      },
      "notification-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://notification-service"
          }
        }
      }
    }
  }
}

Program.cs with Advanced Features:

var builder = WebApplication.CreateBuilder(args);

// Add YARP with service discovery
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
    .AddServiceDiscovery();

// Add authentication
builder.Services.AddAuthentication()
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
        options.Audience = "api://myapi";
    });

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("authenticated", policy =>
        policy.RequireAuthenticatedUser());
});

// Add rate limiting (.NET 9)
builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("fixed", opt =>
    {
        opt.Window = TimeSpan.FromMinutes(1);
        opt.PermitLimit = 100;
        opt.QueueLimit = 10;
    });

    options.AddSlidingWindowLimiter("sliding", opt =>
    {
        opt.Window = TimeSpan.FromMinutes(1);
        opt.PermitLimit = 100;
        opt.SegmentsPerWindow = 6;
    });
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

// Map YARP routes with custom middleware
app.MapReverseProxy(proxyPipeline =>
{
    proxyPipeline.Use(async (context, next) =>
    {
        // Add custom headers
        context.Request.Headers.Append("X-Gateway", "YARP");

        await next();

        // Log response
        var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
        logger.LogInformation(
            "Proxied {Method} {Path} -> {StatusCode}", 
            context.Request.Method, 
            context.Request.Path, 
            context.Response.StatusCode);
    });
});

app.Run();

Kubernetes Ingress

Kubernetes Ingress resources manage external access to services, providing HTTP/HTTPS routing with SSL termination.

Ingress Configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/rate-limit: "100"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://app.company.com"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - api.company.com
    secretName: api-tls-secret
  rules:
  - host: api.company.com
    http:
      paths:
      - path: /orders(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: order-service
            port:
              number: 80
      - path: /customers(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: customer-service
            port:
              number: 80
      - path: /payments(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: payment-service
            port:
              number: 80

Gateway API (Next Generation):

Kubernetes Gateway API provides more expressive and extensible routing capabilities.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: api-gateway
  namespace: production
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - name: api-tls-secret
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: order-route
  namespace: production
spec:
  parentRefs:
  - name: api-gateway
  hostnames:
  - "api.company.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/orders
    backendRefs:
    - name: order-service
      port: 80
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /

Best Practices

Health Checks

Implement comprehensive health checks for proper service discovery and load balancing.

builder.Services.AddHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database")
    .AddCheck<RedisHealthCheck>("redis")
    .AddHttpClient("order-service", client =>
    {
        client.BaseAddress = new Uri("http://order-service");
    })
    .AddCheck("order-service-health");

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = _ => true,
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live")
});

Observability

Enable distributed tracing and metrics for monitoring service communication.

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddSource("OrderService");
    })
    .WithMetrics(metrics =>
    {
        metrics
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddRuntimeInstrumentation();
    });

Security Considerations

Always use HTTPS for external service communication
Implement mutual TLS (mTLS) for service-to-service communication
Use service mesh (Linkerd, Istio) for advanced security policies
Apply principle of least privilege for service accounts
Regularly rotate credentials and certificates
Implement API keys or OAuth for external API access

Summary

Service discovery is fundamental to building resilient microservices architectures. .NET 9 provides native service discovery capabilities that integrate seamlessly with Kubernetes, Azure Container Apps, and custom solutions. Combining service discovery with API gateways like YARP or Azure API Management creates a robust, scalable foundation for distributed applications.

Choose your approach based on your infrastructure:

Kubernetes: Use native DNS with .NET service discovery
Azure Container Apps: Leverage built-in service discovery or Dapr
Hybrid/Multi-cloud: Implement YARP or Azure API Management for unified routing

Always prioritize observability, security, and resilience patterns to ensure production-ready services.

DEV Community: dotnet

How a .NET dev built an AI assistant

The feature

30-second AI glossary

Part 0: I refused to get vendor-locked

A small rant about Semantic Kernel

Part 1: “just use SignalR for everything”

Part 2: AG-UI does most of it for free

What about audio?

Part 3: split the planes

The downside

Part 4: voice is still very much open

Why not WebRTC?

Latency: looks scary, currently fine

What is still unresolved

What I’d tell past me

What this article is really about

Most .NET background job systems are wrong.

Back to Simplicity: Why We Built CALM, a Lock-Free Single-Thread Messaging Library for .NET

The Magic of UI Thread + Event-Driven + async/await

Divide and Conquer, Dependency Management, and CQS

The Trap of Multi-Threading and Race Conditions

8 Years Later: The Birth of CALM

1. Unleashing Power with Native Tasks (async/await)

2. Consistency via Outbox / Unit of Work

3. Guardrails via a Powerful Roslyn Analyzer (Boosting DX)

4. Intentional Multi-Threading Offloading

Conclusion

Building a Page Cache That Doesn't Count: Epoch-Based Memory Management

📍 Where we are

🧾 The obvious answer, and its bill

⏱️ The reframe: stop counting, start timing

⚙️ How it actually works

📊 The numbers

⚖️ Trade-offs, and the one place pure epochs weren't enough

🧰 Two details worth stealing

🎯 The takeaway

⏭️ What's next

Azure Table Storage: The Middle Ground Between a SQL Table and a Document Database

What Azure Table Storage Actually Is

Where Table Storage Actually Sits

Core Concepts

Reading and Writing From C

The Query Language, and Its Real Limitation

Why The Limitation Is Actually The Point

A Genuine Naming Trap Worth Knowing

An Honest Three-Way Comparison

Key Lessons

Summary

GitHub Copilot CLI Slash Commands Every .NET Developer Should Know

Getting Started: Installing and Authenticating Copilot CLI

/model: Switch AI Models On the Fly

/delegate: Let AI Agent Handle Your Repetitive .NET Tasks

/context and /compact: Control Token Usage in Large .NET Solutions

/allow-all and /deny-Tool: Manage Permissions Safely

The Bottom Line

One hyphen, two tenants, one signing key

The one-line bug

Why nothing caught it

The second collision, for free

The fix: injective by construction

Why we are telling you

Ensuring Thread Safety — .NET core-centric

Prefer immutability

Avoid shared state

Use lock / SemaphoreSlim cautiously

Leverage actor-style or message queues

Timeouts, cancellation, and async correctness

Observability for thread-safety issues

Quick decision guide

Synchronous vs asynchronous in .NET core - how decide

Rule of thumb

The core idea

When to choose async

When sync is acceptable

Pitfalls to avoid

Mini decision checklist

ASP.NET Core examples

Tuning & tips

Shared Libraries Management in .NET and Azure

1. Unleashing Power with Native Tasks (`async/await`)

Use `lock` / `SemaphoreSlim` cautiously