DEV Community: Anton B

Implementing an In-Process Actor Model in .NET via System.Threading.Channels and Events

Anton B — Mon, 22 Jun 2026 14:12:17 +0000

Workflow Isolation: Building In-Process Actors in .NET Without Frameworks

Abstract

In the Go world, the CSP (Communicating Sequential Processes) concept and goroutines communicating via channels have become the de facto standard for building scalable systems. In the .NET ecosystem, developers more often rely on classic async/await, which, while solving the problem of CPU thread blocking, imposes hidden architectural limitations: the code of the called class is often executed in the context of the caller's thread.

In this article, we will explore how to elegantly port the philosophy of Go channels to C# classes without using heavy third-party frameworks like Akka.NET. We will break down the "Isolated Actor" pattern, which combines lightweight built-in System.Threading.Channels queues with the standard C# event mechanism. This approach allows us to implement asynchronous message passing within a single process, ensuring strict adherence to the principles of Workflow Isolation and Workflow Single Responsibility at the level of individual system components.

Introduction: Rethinking Multithreading in .NET

Are you familiar with the situation: you open the logs of a high-load service and see how the business logic of a single class is executed across five different Thread Pool threads, replacing each other? Classic async/await blurs the execution context. When ActorA calls a method of ActorB, the receiver's code unceremoniously "hijacks" the current pool thread for its own needs. As a result, the mental model of predictable execution is violated, and debugging turns into a detective story.

The famous manifesto by the creators of the Go language states: "Do not communicate by sharing memory; instead, share memory by communicating." But what if we apply this principle within the C# ecosystem?

Important Architectural Note:

The terms in this article are based on the concept of Workflow Isolation. Since in modern .NET we operate with Task abstractions, under the hood the scheduler (TaskScheduler) can switch physical OS threads on every asynchronous transition (await). We focus specifically on the isolation of the workflow: the workflow (an abstraction) allocated for processing the tasks of a specific actor will never be used to execute code of classes outside the actor's area of responsibility.

Using the modern .NET stack, we can design an architecture where each class exclusively owns its own isolated workflow, and interaction between them is built on asynchronous FIFO buffers. After reading this article, you will learn how to create autonomous in-process actors that exchange messages via Go-style events, maintaining strict ordering and purity of the execution pipeline.

The Illusion of Isolation in Async C# and the "Thread Hijacking" Problem

Most .NET developers are used to perceiving the async/await keywords as synonymous with safe multithreading. We write asynchronous code to avoid blocking threads, and it intuitively seems that since methods execute asynchronously, the system components themselves operate independently of each other.

However, this is an illusion. Architecturally, async/await solves the problem of efficient CPU resource utilization, but it does not solve the problem of execution context isolation.

The Problem: How Standard async/await "Hijacks" Context

Consider a classic situation. We have two services: OrderService (processes orders) and NotificationService (sends notifications). They are written according to standard canons:

public class OrderService
{
    private readonly NotificationService _notificationService;

    public async Task CreateOrderAsync(Order order)
    {
        // 1. Order creation logic (executed in Thread No. 1)
        await SaveToDbAsync(order);

        // 2. Calling a method of another service
        await _notificationService.SendEmailAsync(order.UserId, "Order created");
    }
}

What happens at the OS and Thread Pool level when SendEmailAsync is called?

Since calling an asynchronous method in C# involves unfolding a state machine, Thread No. 1, which was just processing the order logic inside OrderService, freely enters the SendEmailAsync method and starts executing the notification logic.

If a real asynchronous wait occurs inside SendEmailAsync (e.g., a network request to an SMTP server), Thread No. 1 is released. But when the network response returns, the continuation of the SendEmailAsync method is picked up by any random thread from the Thread Pool (let's say Thread No. 2). And it is this Thread No. 2 that, having finished sending the email, will return back to OrderService and continue executing the remaining code there.

From a hardware perspective, this is efficient. From an architectural perspective, it's chaos:

Violation of responsibility boundaries: The code of an external service (NotificationService), which is far outside the boundaries of OrderService's responsibility, is executed within the current order creation workflow.
Implicit delays and blockages: Instead of doing its direct job, the OrderService workflow is forced to idle and wait for the complete completion of someone else's computations. The component completely loses control over which specific tasks are currently consuming the resource allocated to its workflow.

The Solution: Architectural Shift to Workflow Isolation and Workflow Single Responsibility

To bring order to complex distributed systems within a single process, we need to rethink object interaction. Instead of direct method calls, we transition to the concept of Isolated Actors.

We introduce two key rules:

Workflow Isolation: The workflow allocated for processing the tasks of a specific actor will never be used to execute code of classes outside the actor's area of responsibility.
Workflow Single Responsibility: The allocated workflow of an actor has the right to execute only the business logic for which this specific actor is responsible.

Two actors no longer call each other's methods directly. They throw data structures into channels. Our actor no longer exposes heavy methods like SendEmailAsync. Instead, it has:

An incoming buffer (Mailbox): A fast, thread-safe FIFO queue based on System.Threading.Channels.
Its own worker: An infinite loop launched in Task.Run that sequentially reads this buffer.

When OrderService wants to send a notification, it no longer executes the sending code. It simply calls the instantaneous, non-blocking SendAsync() method into the NotificationService buffer (equivalent to the ch <- message operation in Go) and immediately goes back to its own business. The order workflow is completely isolated from foreign contexts, and the ordering of messages is guaranteed by the channel structure.

Anatomy of an "Isolated Actor" Based on System.Threading.Channels

Let's move on to the practical implementation. To build an efficient in-process message passing system, a standard ConcurrentQueue<T> won't do—you'd have to build complex locking and signaling logic around it using SemaphoreSlim or TaskCompletionSource.

In modern .NET, the System.Threading.Channels library is perfectly suited for these purposes. It is an ultra-fast, thread-safe data structure implementing the "Producer-Consumer" pattern with near-zero memory allocation.

Below is the complete code for our SequentialActor. It strictly preserves ordering, isolates the workflow, and correctly releases resources.

using System;
using System.Threading;
using System.Threading.Channels;
using System.Threading.Tasks;

// Event argument class for passing data between actors
public class ActorMessageEventArgs : EventArgs
{
    public string Payload { get; }
    public string SenderName { get; }

    public ActorMessageEventArgs(string payload, string senderName)
    {
        Payload = payload;
        SenderName = senderName;
    }
}

public class SequentialActor : IDisposable, IAsyncDisposable
{
    private readonly Channel<string> _buffer;
    public string Name { get; }

    private readonly CancellationTokenSource _cts;
    private Task? _processingTask;
    private bool _isDisposed;

    // Feedback event for other actors
    public event EventHandler<ActorMessageEventArgs>? MessageProcessed;

    public SequentialActor(string name)
    {
        Name = name;
        _cts = new CancellationTokenSource();

        // Configuring channel optimization for the actor architecture
        _buffer = Channel.CreateUnbounded<string>(new UnboundedChannelOptions
        {
            // FIFO GUARANTEE: We explicitly specify that only ONE worker will read from the buffer.
            // This disables internal read contention and guarantees strict ordering.
            SingleReader = true,

            // Disallow synchronous continuations so that the calling workflow thread does not get
            // pulled into the pipeline processing logic when the buffer is filled/freed.
            AllowSynchronousContinuations = false
        });
    }

    /// <summary>
    /// Non-blocking method to write a message to the actor's buffer.
    /// Can be safely called concurrently from any other threads.
    /// </summary>
    public async ValueTask SendAsync(string message)
    {
        ObjectDisposedException.ThrowIf(_isDisposed, this);
        await _buffer.Writer.WriteAsync(message);
    }

    /// <summary>
    /// Starts the actor's lifecycle. Creates an isolated workflow.
    /// </summary>
    public void StartProcessing()
    {
        ObjectDisposedException.ThrowIf(_isDisposed, this);
        if (_processingTask != null) return;

        _processingTask = Task.Run(async () =>
        {
            try
            {
                // The ReadAllAsync method returns an async stream (IAsyncEnumerable).
                // The loop will extract messages strictly in FIFO order.
                await foreach (var message in _buffer.Reader.ReadAllAsync(_cts.Token))
                {
                    // Workflow Isolation point: processing code is executed STRICTLY sequentially.
                    // The actor's workflow performs exclusively its internal tasks,
                    // adhering to Workflow Single Responsibility. The next message will not start
                    // processing until the current await completes.
                    await ProcessMessageInternalAsync(message);

                    // Notify subscribers via event
                    OnMessageProcessed(new ActorMessageEventArgs(message, Name));
                }
            }
            catch (OperationCanceledException)
            {
                // Standard cancellation via CancellationToken
            }
            catch (Exception ex)
            {
                // Business logic errors should not crash the entire application lifecycle
                LogError(ex);
            }
        });
    }

    private async Task ProcessMessageInternalAsync(string message)
    {
        // Simulating useful class work (DB operations, HTTP requests, etc.)
        await Task.Delay(100, _cts.Token);
    }

    protected virtual void OnMessageProcessed(ActorMessageEventArgs e)
    {
        MessageProcessed?.Invoke(this, e);
    }

    private void LogError(Exception ex) => Console.WriteLine($"[{Name}] Error: {ex.Message}");

    #region Resource Cleanup Interfaces Implementation (Graceful Shutdown)

    public async ValueTask DisposeAsync()
    {
        if (_isDisposed) return;
        _isDisposed = true;

        // 1. Gracefully close the buffer for writing.
        // New messages are not accepted, but the ReadAllAsync loop will continue working
        // until it processes ALL messages already in the queue.
        _buffer.Writer.TryComplete();

        // 2. Wait for the workflow to completely finish draining the queue
        if (_processingTask != null)
        {
            try { await _processingTask; } catch { }
        }

        MessageProcessed = null; // Protect against memory leaks via events
        _cts.Dispose();
        GC.SuppressFinalize(this);
    }

    public void Dispose()
    {
        if (_isDisposed) return;
        _isDisposed = true;

        _buffer.Writer.TryComplete();
        _cts.Cancel(); // In a synchronous scenario, we have to forcefully interrupt processing

        _processingTask?.GetAwaiter().GetResult(); // Safe blocking wait for Task
        MessageProcessed = null;
        _cts.Dispose();
        GC.SuppressFinalize(this);
    }

    #endregion
}

Architectural Accents of the Code:

The SingleReader = true flag: Under the hood, System.Threading.Channels switches to a highly optimized data structure. It doesn't need to check if another thread is trying to grab the element simultaneously. This provides a colossal speed boost and reduces CPU load.
The AllowSynchronousContinuations = false parameter: If not set, the thread writing a message via SendAsync might be forcibly involved by the scheduler in executing the worker's logic itself. By setting it to false, we strictly separate contexts: the sender thread only puts data in and leaves instantly.
Dual Dispose implementation: In the async world, it's important to give the system a chance to finish gracefully (Graceful Shutdown). Closing the writer via TryComplete() signals the code "finish what you managed to grab and shut down smoothly."

Asynchronous Binding of Actors via Events Without Breaking Isolation

When we isolated the computations of each actor within its own incoming buffer, the next architectural question arises: how to organize feedback? For example, how can NotificationService report back to OrderService that the notification was successfully sent?

The most natural way for C# is to use standard events. However, the standard event mechanism in .NET works synchronously. When an actor generates an event (calls Invoke), the code of all subscriber handlers is executed in the exact same workflow thread that triggered the event.

If we simply subscribe one class to the event of another and start executing heavy logic there, we will instantly destroy our entire architecture. The workflow of the first actor will "fly off" to execute the code of the second, violating both Workflow Isolation and Workflow Single Responsibility.

The "Fast Forward" Rule

To prevent events from destroying isolation, we impose a strict architectural regulation on the handler code:

The subscriber has no right to execute business logic inside another actor's event handler. The only thing it is allowed to do is take the data from the event arguments and instantly forward (write) it to its own incoming buffer via SendAsync().

Since writing to an unbounded System.Threading.Channels (CreateUnbounded) happens instantly in memory without any locks, the calling actor's workflow performs this operation in microseconds and immediately returns to its queue. Heavy processing of the event by the subscriber will only begin when its own isolated workflow gets to this message in the FIFO queue.

Implementation of Inter-Actor Communication

Let's see what the secure binding of two actors via events looks like in the main application module:

class Program
{
    static async Task Main(string[] args)
    {
        // Create two isolated actors
        await using var orderActor = new SequentialActor("OrderProcessor");
        await using var notificationActor = new SequentialActor("NotificationWorker");

        // SUBSCRIPTION (Observing Workflow Isolation):
        // When OrderActor finishes processing, we notify NotificationActor.
        orderActor.MessageProcessed += (sender, e) =>
        {
            // Note: this lambda expression is executed in the OrderActor's workflow!
            // Therefore, there should be no heavy logic here.
            string taskForNotification = $"Send email for order: {e.Payload}";

            // Instant forward to the neighbor's buffer.
            // The OrderActor's workflow is released in fractions of a microsecond.
            _ = notificationActor.SendAsync(taskForNotification);
        };

        // Launch independent workflows for each actor
        orderActor.StartProcessing();
        notificationActor.StartProcessing();

        // Send a start signal from the external context
        await orderActor.SendAsync("Order No. 1024");

        // Give actors time to sequentially execute their tasks
        await Task.Delay(500);
    }
}

Why is the `_ = notificationActor.SendAsync()` call absolutely safe here?

The Fire-and-Forget construct (via ignoring ValueTask) is usually considered an anti-pattern, but here it is justified and safe:

Specifics of the unbounded buffer: The SendAsync method writes to Channel.CreateUnbounded. Such an in-memory queue is always ready to accept an element. The buffer addition operation executes synchronously and instantly. Under the hood, WriteAsync immediately returns an already completed ValueTask (with the IsCompleted = true flag). No allocations for the async/await state machine and no context switches occur.
Isolation guarantee from the neighbor: Thanks to the AllowSynchronousContinuations = false flag, even if the NotificationActor was idle and waiting for data at that moment, its awakening will happen strictly in the thread pool via the TaskScheduler. It physically cannot "hijack" the OrderActor's workflow.
Predictable error interception: If the neighbor's buffer is closed (Dispose is called), the WriteAsync method will throw a ChannelClosedException synchronously at the moment of the call. The error won't hang in the background but will instantly bubble up to the try-catch block of the current actor, where it will be correctly handled without risking crashing the process.

Conclusion: The Architectural Manifesto of the "Isolated Actor"

Implementing the "Isolated Actor" pattern based on System.Threading.Channels and C# Events is a powerful way to bring order to the asynchronous code of .NET applications. Porting the philosophy of Go channels to C# classes allows us to move away from the chaotic task distribution inherent in standard async/await and transition to a strictly deterministic, predictable execution model.

Main Takeaways of Applying the Pattern

Workflow Isolation in action: Each actor turns into an impregnable fortress. The workflow allocated for its tasks is completely protected from the invasion of foreign code, making logging linear and debugging trivial.
Workflow Single Responsibility at the design level: System components no longer share CPU time within a single end-to-end call. An actor's workflow is completely insured against idleness and blockages: it will never hang waiting for the execution of foreign tasks outside the scope of the current component's responsibility. Instead, it instantly delegates external work via the buffer and immediately proceeds to process the next message in its queue.
High performance: Message passing occurs within RAM with near-zero allocation and speeds of millions of operations per second, thanks to the low-level optimizations of the Channels library.
Safe Fire-and-Forget: Binding actors via events with instant data forwarding is an absolutely reliable architectural solution, as the write operation is atomic, synchronous under the hood, and physically cannot cause deadlocks.

When Should You Apply This Approach?

This pattern is ideal for systems with complex internal data processing logic within a single process:

Data Processing Pipelines: When data must pass through a chain of sequential stages (e.g., validation ➔ enrichment ➔ writing to DB ➔ sending a notification).
Integration Gateways and Parsers: Where it is necessary to quickly read external sources and pass tasks for processing to internal services without blocking the reading thread.
Local Background Services: Implementing complex scenarios inside BackgroundService in ASP.NET Core without involving heavy external message queues like RabbitMQ.

Final Conclusion

You don't always need heavy distributed frameworks like Akka.NET or Proto.Actor to get the benefits of the actor model. Modern .NET provides developers with concise, lightweight, and incredibly fast tools right "out of the box." The "Isolated Actor" pattern proves that adhering to strict workflow hygiene and proper separation of execution contexts allows you to write the most complex multithreaded systems while keeping the code clean, safe, and easy to understand.

AI Assistants — The Wiki-First Approach

Anton B — Wed, 15 Apr 2026 08:00:29 +0000

In modern projects, the codebase grows exponentially, and AI assistants have become an integral part of the development workflow. However, without a single source of truth, every developer (and every AI agent) is forced to learn the project from scratch, wasting context window limits, time, and resources. The wiki-first approach solves this problem by turning documentation into a living, automatically maintained knowledge center that dictates how both humans and AI operate.

📌 Note: All structural examples, file names (QWEN.md, .qwen/skills/), and workflows in this article are provided for the QWEN ecosystem. The methodology itself is universal and can easily be adapted to any AI agent capable of working with Markdown instructions.

🔍 What is Wiki-First?

Wiki-first is a methodology where, before any work with the code (writing features, reviewing, refactoring, making architectural decisions), the developer or AI agent must first study the project's wiki documentation (docs/wiki/).

Key principle:

Wiki = overview, Code = details

The wiki stores condensed, structured knowledge: system architecture, accepted patterns, service dependencies, naming conventions, and DI rules. Specific method signatures, SQL queries, or test assertions are looked up directly in the code if the wiki does not cover the task.

🚀 Benefits of the Approach

Aspect	Without Wiki-First	With Wiki-First
Project Onboarding	Everyone learns the code from scratch	Ready-made overview in 5 minutes
Knowledge Storage	Knowledge stays in developers' heads	Knowledge is centralized in the wiki, accessible to all
Onboarding	Newcomers spend days deciphering the code	Newcomers read the wiki → hours instead of days
AI Agent Workflow	Wastes context scanning thousands of lines	Reads concise wiki pages, saving tokens and time
Documentation Freshness	Wiki falls behind the code, quickly becomes outdated	Wiki is automatically updated after every change
Standard Compliance	Developers violate patterns out of ignorance	AI and humans follow unified rules from the wiki

🛠 How to Set Up Wiki-First in Your Project

For quick and correct setup, use the WIKI_FIRST_TEMPLATE.en.md template. It is designed for execution by an AI agent, which will automatically create the entire knowledge infrastructure and skills.

Step 1. Prepare Parameters

Copy WIKI_FIRST_TEMPLATE.en.md to the root of your repository.
Open the file and fill the INPUT DATA table with real values:

Parameter	Example
`project_name`	`WebArchiveBackend`
`project_description`	`Backend API for storing and indexing web pages`
`tech_stack`	`C#, .NET 8, gRPC, PostgreSQL, Dapper`
`docs_path`	`docs/`
`wiki_path`	`docs/wiki/`
`skills_path`	`.qwen/skills/`
`source_dirs`	`src/, tests/`

Step 2. Launch the AI Agent

Pass the filled file to your AI assistant with the following prompt:

"Execute the instructions from WIKI_FIRST_TEMPLATE.en.md strictly step-by-step. Create the wiki structure, AI skills, and the main rules file. Do not modify the existing project code. After creating the structure, perform the Initial Ingest (Step 6)."

The agent will automatically:

Create the docs/wiki/ directory and three base files:
- index.md — catalog of all wiki pages
- log.md — change log (append-only)
- Wiki Format.md — guide to page formatting
Generate three specialized AI skills in .qwen/skills/:
- wiki-workflow — knowledge management (ingest, query, lint, post-change lint)
- code-contributor — writing and modifying code according to standards
- code-architecture — architectural review (SOLID, DI, layered architecture)
Create QWEN.md in the project root with a strict wiki-first rule and source hierarchy: docs/wiki/ > Project code.

Step 3. Initial Project Analysis (Initial Ingest)

After creating the structure, the agent will execute Step 6 from the template:

Scans the source code directories (source_dirs).
Generates initial wiki pages: Architecture.md, Components.md, Database.md, Code Patterns.md, Testing.md.
Updates index.md, adding new pages to the catalog.
Adds an entry to log.md about the initial knowledge load.
⚠️ Important: The wiki contains only overviews and relative links to files. Copying code from .cs, .proto, or .sql files is prohibited.

Step 4. Verify Installation

After the agent finishes, verify the result using the checklist:

[ ] QWEN.md contains the wiki-first rule and source priority
[ ] docs/wiki/ contains index.md, log.md, Wiki Format.md
[ ] .qwen/skills/ contains 3 SKILL.md files
[ ] All skills explicitly state: wiki > code
[ ] Base wiki pages for architecture, components, and patterns are generated
[ ] index.md contains links to all created pages
[ ] log.md contains an entry about the first ingest with date and description

🔄 How to Work with Wiki-First After Setup

Role	Rule
Developer	Before a task → open `docs/wiki/index.md`. After committing → update wiki + add an entry to `log.md`.
AI Agent	Any request → wiki first. After code changes → post-change lint. Missing details → read code.
Code Review	If a PR didn't update the wiki → request changes. Wiki must not diverge from the code.

Typical AI agent workflow:

Wiki-first → reads index.md → finds relevant pages
Query/Ingest → clarifies details in code if needed
Code → writes feature/fix according to wiki patterns
Post-Change Lint → updates wiki and log.md
Verify → checks links, frontmatter, code alignment

🔄 Wiki Lifecycle: Maintenance, Consistency, and Skill Evolution

Setting up wiki-first is not a one-time configuration, but the launch of a living process. Documentation left unattended quickly becomes a "knowledge graveyard." To ensure the approach delivers long-term value, the wiki must be continuously updated, and the AI agent must act as the primary guarantor of its consistency and completeness.

🤖 Agent as the Guardian of Integrity

After the initial setup, responsibility for wiki freshness falls on the AI agent. With every code change, the agent must automatically run a post-change lint: check if existing pages contradict the new implementation, update descriptions of affected components, and log changes in log.md.

Require explicit synchronization confirmation from the agent. If a commit affects architecture, configuration, or adds new modules, the agent must not only fix the code but also update the wiki. This turns documentation from an "extra burden" into an integral part of the development cycle. Without this step, the wiki will quickly drift from the code, and the wiki > code rule will lose its meaning.

📖 Documenting Complex Scenarios

The true power of wiki-first emerges when not only static descriptions but also project-specific workflows are added to the knowledge base.

For example, adding a new configuration parameter in your project might require changes in five different places: from appsettings.json to DI container objects, DTO models, and DB migrations. Instead of explaining this to the agent from scratch every time, document this scenario once as a separate wiki page or a section in Code Patterns.md.

Once a complex scenario is documented in the wiki, the agent begins executing it confidently, without hallucinations or missed steps. When asked "Add parameter X", the agent:

Finds the instruction in the wiki via index.md.
Strictly follows the described sequence of changes.
Automatically updates the wiki if the scenario needs adaptation to new realities.

The more "routine" and "easily forgotten" scenarios you formalize in the wiki, the less time is spent micromanaging the agent, and the higher the stability of the results.

🧠 Model-Specific Nature of Wiki

Different LLM models structure thoughts, choose priorities, and formulate instructions differently. This is not a bug, but a feature. When an agent itself generates the wiki during initial analysis (Initial Ingest) or subsequent updates, the documentation naturally "adapts" to its internal logic, tokenization, and attention patterns.

A model will follow a wiki it generated or curated itself much more accurately and confidently than documentation written by another model or a human "for themselves." Therefore, do not strive for perfect "human" stylistics in the early stages. The main thing is that the structure is unambiguous, links work, and the update logic is maintained. Over time, you will notice that the wiki becomes the "native language" of your agent: it finds context faster, hallucinates less, and executes complex tasks more precisely.

🛠 Evolution of Skills and Rules

The skills created during setup are not set in stone. As the project grows and experience with the agent accumulates, they must be adapted:

If the agent frequently misses a certain type of check, add the corresponding rule to code-architecture or wiki-workflow.
If new tech stacks or patterns emerge, expand code-contributor with examples and conventions.
If the wiki structure becomes too bulky, refactor index.md, introduce tags, or split monolithic pages into thematic blocks.

The QWEN.md and SKILL.md files themselves are part of the wiki ecosystem. They can and should be refactored to keep instructions precise, minimize context consumption, and match the current maturity stage of the project.

💡 Core Principle: Wiki is a Living Organism

The key idea of the approach is this: you cannot just create a wiki, you must continuously develop it.

Maintain freshness: every code change → wiki change + entry in log.md.
Enrich context: turn verbal agreements, bug trackers, and complex manual procedures into formalized wiki instructions.
Evolve the agent: adapt skills, clarify priorities, and refine prompts for real project tasks.

When the wiki becomes the single source of truth, and the agent acts as its active curator, the team gets a scalable knowledge system. It doesn't "wither" over time but gains strength: the more you invest in it, the faster, more accurate, and more confident the AI works, reducing time spent on onboarding, code reviews, and bug fixing.

💡 Conclusion

The wiki-first approach transforms documentation from an "artifact that gets forgotten" into an active development tool. AI agents operating under these rules save context, strictly adhere to architectural standards, and accelerate feature delivery.

Set up wiki-first once using WIKI_FIRST_TEMPLATE.en.md, integrate it into your CI/CD and onboarding processes, and you will get a scalable knowledge system that grows with your project rather than turning into legacy.

Shadow Logging via Events - Complete Decoupling of Business Logic and Logging in DI Environment

Anton B — Sun, 08 Feb 2026 09:51:27 +0000

Hello, colleagues!

I want to share an approach to logging that radically simplifies architecture and strengthens SOLID principles.

I've created a code example on GitHub to demonstrate how shadow decoupled logging works through C# events.

What is Decoupled Logging?

Decoupled logging is an architectural approach where business classes do not contain direct logger calls (like ILogger.LogInformation). Instead:

Business classes generate events.
Specialized logger classes handle the events.
Business classes know nothing about loggers.
Logging is configured centrally at the application level, without polluting domain logic.

Pros and Cons of Decoupled Logging

There are opinions both "for" and "against" decoupled logging.

Typical arguments "for":

SRP purity: The class focuses on business logic; logging is an external concern.
Testability: No ILogger mocks needed; classes work standalone.
Flexibility and scalability: One event can be handled in all required ways: logs, metrics, audit. Easy to change event handling logic and logging libraries.
Decoupling for libraries: Consumers of business logic classes decide themselves whether to log events and which ones. No hard dependencies.
Performance: Business class does not format data for logs. When implementing event handlers, use smart fast caching of incoming events with subsequent post-processing - it doesn't block business logic.

Critics' objections boil down to a simple thesis: don't complicate things if not really needed - "inject ILogger and don't worry." This opinion sounds reasonable; I agree with such criticism - if you have a simple application, don't complicate it.

Extracting Logging from the Class

The simplest way to separate business logic and logging is to write a Wrapper for the business class.

Decorator/wrapper for logging is convenient but imposes usage rules:

Client code must work through the wrapper.
Refactoring becomes more complex.
Duplication and inheritance issues arise.

This approach makes logging not "shadow" - consumers indirectly know about it.

Complete Separation

Complete separation of business logic and logging is possible only using two independent objects: business class and log handler.

Simple example:

class OrderServiceLogger
{
    public OrderServiceLogger(FileLogger logger, OrderService orderService)
    {
        orderService.OrderCreated += (s, e) => logger.LogInformation($"Order {e.OrderId} created.");
    }
}

var orderService = new OrderService();
var fileLogger = new FileLogger();
var orderServiceLogger = new OrderServiceLogger(fileLogger, orderService);
orderService.CreateOrder(...);

This approach is straightforward, but if the application uses a DI container, it requires adaptation.

Shadowing Logging

DI containers perform 2 important tasks:

Object factory
Object lifetime management

Object creation is simple: the DI container will return 2 ready objects, with the log handler receiving the business class instance and logger instance upon creation.

var services = new ServiceCollection();
services.AddScoped<FileLogger>();
services.AddScoped<OrderServiceLogger>();
services.AddScoped<OrderService>();
var serviceProvider = services.BuildServiceProvider();

var orderService = serviceProvider.GetRequiredService<OrderService>();
var orderServiceLogger = serviceProvider.GetRequiredService<OrderServiceLogger>();

The problem is managing the lifetime of the log handler OrderServiceLogger, i.e., explicitly storing a reference to the created object and synchronizing its lifetime with the business class OrderService instance.

If we do nothing else, we'll have to explicitly create a new OrderServiceLogger instance wherever we create an OrderService instance and ensure their lifetimes match - that's not the behavior we want.

What we need:

Use only business logic object instances in business logic, in our example OrderService.
Business logic should know nothing about objects performing other tasks in the application, in our example logging via OrderServiceLogger.
When creating a business logic object, the application must guarantee all implemented service functions for it - if OrderServiceLogger is implemented for OrderService, it must be created in time and handle events.
Correct service function operation includes optimal application resource management - the OrderServiceLogger instance must be removed from memory after the associated OrderService object is destroyed.

These requirements are easy to implement, even within a DI container. We've sorted object creation; now we need to implement lifetime synchronization using weak references.

We need to ensure the created OrderServiceLogger object lives no less than the OrderService instance and is removed when no longer needed.

For this, we need an application-level object that:

Stores references to both dependent objects.
Monitors their lifetimes.
Removes OrderServiceLogger as soon as OrderService is removed.

We can implement such a class ourselves, where there is a key object and dependent objects. The architecture of such a class is simple:

Key object(s) are stored as weak references, which do not prevent the object from being garbage collected.
Dependent objects are stored as strong references, which prevent the garbage collector from destroying them.
The state of key objects is periodically checked - if they are removed, dependent objects are also removed.

For the simple case, we can use the ConditionalWeakTable class from the System.Runtime.CompilerServices namespace, which already implements this logic.

Writing DI Logic

Let's implement an extension method for ServiceCollection and examine how it works.

public static class ServiceCollectionExtensions
{
    public static ServiceCollection AddScopedWithLogger<TService, TServiceInstance, TServiceLogger>(
        this ServiceCollection services)
        where TService : class
        where TServiceInstance : class, TService
        where TServiceLogger : class
    {
        // Register TServiceInstance.
        services.AddScoped<TServiceInstance>();
        // Register TServiceLogger.
        services.AddScoped<TServiceLogger>();
        // Register TService.
        services.AddScoped<TService>(sp =>
        {
            var instance = sp.GetRequiredService<TServiceInstance>();
            var logger = sp.GetRequiredService<TServiceLogger>();
            var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
            // Put instance and logger into ConditionalWeakTable.
            conditionalWeakTable.Add(instance, logger);

            return instance;
        });

        return services;
    }
}

The AddScopedWithLogger method does all the necessary work:

Registers all types in DI.
Implements the logic for creating and linking the business class and its event handler class.

Important - in the DI container, it is necessary to separate the logic for creating the business class object itself from the logic for creating the instance with all its shadow objects. For this, it is best to use business class contracts (interfaces).

public class OrderEventArgs : EventArgs
{
    public int OrderId { get; set; }
}

public interface IOrderService
{
    event EventHandler<OrderEventArgs> OrderCreated;
    void CreateOrder(int id, string customer);
}

Thus, the DI container will pass the OrderService instance to the OrderServiceLogger constructor.

In business logic, only contracts must be used, which is a recommended approach.

class OrderManager : IOrderManager
{
    public OrderManager(IOrderService orderService)
    {
        ...
    }
}

Correctly register all types in the container:

var services = new ServiceCollection();
services.AddScopedWithLogger<IOrderService, OrderService, OrderServiceLogger>();

Now, creating an object for its contract IOrderService will trigger the following code from the extension method:

// Register TService.
services.AddScoped<TService>(sp =>
{
    var instance = sp.GetRequiredService<TServiceInstance>();
    var logger = sp.GetRequiredService<TServiceLogger>();
    var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
    // Put instance and logger into ConditionalWeakTable.
    conditionalWeakTable.Add(instance, logger);

    return instance;
});

Here's the breakdown for the parameter combination IOrderService, OrderService, OrderServiceLogger:

services.AddScoped<IOrderService>(sp =>
{
    var instance = sp.GetRequiredService<OrderService>();
    var logger = sp.GetRequiredService<OrderServiceLogger>();
    var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
    // Put instance and logger into ConditionalWeakTable.
    conditionalWeakTable.Add(instance, logger);

    return instance;
});

As you can see, it's simple. OrderService and OrderServiceLogger objects are created with all dependencies, then both objects are saved in the ConditionalWeakTable<object, object>.

var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
// Put instance and logger into ConditionalWeakTable.
conditionalWeakTable.Add(instance, logger);

The ConditionalWeakTable<object, object> object itself must be registered in the DI container with a lifetime equal to or greater than OrderService and OrderServiceLogger.

I recommend using Scoped if the registered objects live no longer. Singleton is not necessary.

And the last piece of the puzzle - at the application level, create a ConditionalWeakTable<object, object> instance that lives no less than the objects stored in it.

Simplest example:

class Program
{
    private static void Main()
    {
        var services = new ServiceCollection();
        services.AddScoped<ConditionalWeakTable<object, object>>();

        // Registration of all types and other application service code
        ...
        ...

        // Instance of ConditionalWeakTable that holds references to shadow objects.
        var conditionalWeakTable = serviceProvider.GetRequiredService<ConditionalWeakTable<object, object>>();
        // Start application work.
        Run(...);
    }
}

Conclusion

Advantages of the approach as I see them:

Logger is automatically bound to a specific class instance.
Weak references guarantee operation without memory leaks.
Centralized subscription in the DI container.
Ability to flexibly extend the number of shadow services and manage them.
Strong SOLID with minimal compromises.

I recommend using it for serious projects where quality architecture provides a tangible advantage.