DEV Community: Yander Santiesteban Rojas

The Mediator Pattern's Visibility Tax: Profiling and Debugging Your Pipeline Inside the IDE

Yander Santiesteban Rojas — Thu, 30 Jul 2026 22:00:00 +0000

In the first post of this series, we removed the mediator pattern's runtime tax: source-generated dispatch measured 0.99× of a direct call in a realistic three-behavior benchmark, and the mediator's own per-Send overhead stays a constant 72 B no matter how deep the pipeline gets.

But there's a second tax, and no benchmark can refund it: the visibility tax. In any grown CQRS codebase:

Hidden behaviors silently wrap every dispatch (validation, logging, retry, transactions) and nobody remembers the chain.
Nested mediator calls inside handlers turn a single endpoint into a dozen invocations the IDE won't show you.
Notification fan-out scatters business effects across projects; tracing them takes grep and luck.
Cross-project handlers live in *.Application, get dispatched from *.Api, and decorated in *.Infrastructure; no single source file tells the story.

Here's the thing though: source generation doesn't just make the pipeline fast. It makes the pipeline knowable at compile time. If a generator can emit the whole chain, tooling can show you the whole chain: exactly, not heuristically.

That's what DSoftStudio Mediator Pipeline Explorer is built on. It's an extension for VS Code and for Visual Studio 2022/2026, and it closes one loop: understand → navigate → measure → fix, without leaving the editor.

See the pipeline

Open your solution, build once, and the extension discovers every command, query, notification, and stream: zero registration, zero attributes, zero config files. The pipeline tree groups them CQRS-style, and under each request you see the full chain: pre-processors, behaviors, handler, post-processors, exception handlers. One click (or Ctrl+F12 on a request type; Cmd+F12 on macOS) jumps to the source, including handlers that live three projects away.

The same data renders as an interactive graph, and this is where hidden structure becomes obvious:

Notification fan-out and nested mediator calls are drawn inline, so "one endpoint" that's actually eleven invocations across four projects stops being tribal knowledge.

Debugging a slow pipeline

The static picture is half the value. The other half: the profiler speaks mediator, not spans.

Here's the loop as it plays out on a real solution. Your dashboard flags a pipeline as tail-heavy: p99 way out of proportion to p50. In a generic APM tool, you'd now be digging through trace waterfalls trying to map spans back to behaviors.

Instead, you start a profiling session and hit the endpoint. The graph nodes light up with live timings and heat coloring; the hot node is visually obvious. Then the Hot Path view attributes every millisecond in execution order:

Three things in that view do the actual debugging for you:

External dependency attribution. EF Core query compilation, connection acquisition, individual SQL statements, HTTP calls, all attached to the exact pipeline component that triggered them. "The handler is slow" becomes "this one SQL statement inside this handler is slow." (This level of detail comes from the OpenTelemetry companion package; see the setup notes below.)
Self-wait vs work. Time lost to I/O and async scheduling is separated from CPU time, so you stop optimizing code that was never busy in the first place.
The bottleneck badge. The dominant row is flagged automatically. In a dozen-deep chain, finding the one slow behavior takes seconds.

You fix the offender, profile again, and watch the heat drain out of the graph. That's the whole loop: no add-a-log-line-and-redeploy cycles, no span-to-code guesswork.

Beyond single requests, the statistics dashboard tracks per-pipeline Calls / Errors / p50 / p95 / p99 / Max, flags tail-heavy pipelines against configurable SLO thresholds, and breaks down notification fan-out with per-handler overhead, so you can see what that one innocent Publish actually fans out to. (The repo's domain-events sample is a ready-made playground for this: one POST publishes an event that fans out to three independent handlers.) It profiles apps you launch and processes already running outside the debugger.

Setup: what's automatic, and what isn't

The core profiling (handler and behavior timings, percentiles, fan-out) is wired without touching your code, and under one engineering constraint I care a lot about: the tooling keeps its build wiring out of your repository.

The profiling hooks wire themselves in at compile time when the analyzer loads; nothing to add to Program.cs.
The build wiring is machine-local (per-user), never committed to your repo.
Profiling is scoped to Debug builds by default, so Release and AOT builds ship untouched.
Teammates without the extension and your CI runners build plain, unmodified code.

One part is not automatic, and it's worth being precise about: the external dependency attribution (the EF Core / SQL / HTTP frames in the Hot Path) comes from the DSoftStudio.Mediator.OpenTelemetry companion package, which you install and configure in the app like any OpenTelemetry integration. Without it you still get the full mediator-level picture (component timings, percentiles, fan-out), just not the dependency breakdown inside your handlers.

The integration is a few lines in Program.cs. Here's the wiring from a demo API that inserts users into PostgreSQL and publishes a domain event (the repo's opentelemetry sample shows the same pattern, with metrics and a console exporter):

// Instrumentations ENRICH spans with semantic tags: URL/host, SQL statement,
// pipeline component. Note there's no exporter: nothing leaves the machine.
builder.Services.AddOpenTelemetry()
    .WithTracing(t => t
        .AddAspNetCoreInstrumentation()   // tags the incoming HTTP request
        .AddNpgsql()                      // PostgreSQL spans: statement, host
        .AddMediatorInstrumentation());   // subscribes to the "DSoftStudio.Mediator" source

builder.Services
    .AddMediator()
    .RegisterMediatorHandlers()
    .AddMediatorInstrumentation(o =>
        o.Filter = type => !type.Name.StartsWith("HealthCheck"))  // keep the flame focused
    .PrecompilePipelines()
    .PrecompileNotifications();

Both calls are named AddMediatorInstrumentation(): one registers the instrumentation inside the mediator pipeline (with an options callback; here it filters out health checks), the other subscribes the OpenTelemetry SDK to the mediator's ActivitySource. It's the same wiring you'd write for any OTel instrumentation library.

And note what's missing: an exporter. For the IDE workflow you don't need one. The extension reads the already-enriched spans from the running process, and nothing is exported anywhere. When you also want production observability, add your exporter (OTLP, Application Insights, or any other) and the exact same wiring feeds both.

Either way, adopting the tooling is a personal choice, not a team-wide commit.

Licensing

The library and all companion packages from part 1 are MIT and stay MIT. Pipeline Explorer is commercial software with a free trial; the same activation works in both the VS Code and Visual Studio editions. If a license ever lapses, your code keeps compiling and running on the MIT core: the extension adds visibility on top of your build and never becomes a dependency of it.

If your day job involves a mediator pipeline deeper than three behaviors, point the trial at your gnarliest real solution; that's the fastest honest test of whether it earns a place in your toolbox: mediator.dsoftstudio.com · docs · pricing

That closes the series: source generation removes the runtime cost, and the tooling uses that same compile-time knowledge to remove the blind spots.

The Hidden Runtime Cost of MediatR-Style Pipelines

Yander Santiesteban Rojas — Mon, 27 Jul 2026 22:40:24 +0000

If you've shipped a CQRS codebase on a MediatR-style library, you know the trade-off. The mediator pattern buys you decoupling: thin controllers, one handler per use case, cross-cutting concerns as pipeline behaviors. But it charges two taxes in return:

The runtime tax. Reflection-based dispatch, service resolution on the hot path, and allocations that grow with pipeline depth. At scale, that's GC pressure, and GC pressure shows up directly in your p99.
The visibility tax. The pipeline is assembled at runtime inside the DI container, so nobody can actually see it: which behaviors wrap this command, where that notification fans out, which component is slow.

This post is about removing the first tax with DSoftStudio.Mediator, an MIT-licensed, source-generated mediator for .NET. The second tax gets its own post next in this series.

Where the runtime tax comes from

In a classic runtime-composed mediator, every Send walks the DI container: resolve the handler wrapper, resolve the behavior chain, and wrap each behavior around the next as a delegate with a closure. Three behaviors = three delegate allocations + closures, per request. It works, but you pay in allocations that scale with pipeline depth, and in a call path the runtime can't see through.

The fix isn't micro-optimizing that machinery. It's moving the work to compile time.

DSoftStudio.Mediator does this with a source generator that emits handler discovery and registration, the precompiled behavior chain per request type, closed notification dispatch tables, and C# 12 interceptors that turn Send/Publish/CreateStream call sites into direct typed invocations. By the time your app starts, there is no pipeline left to compose at runtime; what executes is ordinary generated C# you can read in your IDE.

What it looks like

dotnet add package DSoftStudio.Mediator

public record Ping() : IRequest<int>;

public class PingHandler : IRequestHandler<Ping, int>
{
    public ValueTask<int> Handle(Ping request, CancellationToken ct)
        => new ValueTask<int>(42);
}

services.AddMediator(builder =>
{
    builder.AddOpenBehavior(typeof(LoggingBehavior<,>));
    builder.AddRequestPreProcessor<AuditPreProcessor>();
});

var result = await mediator.Send(new Ping()); // that's it

The API is deliberately MediatR-compatible (requests, notifications, streams, behaviors, pre/post processors, exception handlers), so migration is mostly mechanical (handlers return ValueTask instead of Task; there's a migration table in the README). You also get CQRS aliases: ICommand<T> / IQuery<T> with matching handler interfaces.

No magic under the hood

Everything above is ordinary C# emitted into your build: the DI registrations, the typed Send overloads, the dispatch tables. On the hot path there is no reflection, no MakeGenericType, no delegate chain: just a static flag check and a direct, typed Handle call, with a single cached resolve as the only DI touch. That is also why the library is Native AOT and trimming safe by construction: there is no dynamic code path to guard.

And if you ever want to audit exactly what runs, dotnet build -p:EmitCompilerGeneratedFiles=true drops the generated sources under obj/…/generated/. What you register is what runs.

The design detail that makes allocations constant

public interface IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    ValueTask<TResponse> Handle(
        TRequest request,
        IRequestHandler<TRequest, TResponse> next,  // ← not a delegate
        CancellationToken cancellationToken);
}

next is a typed handler, not a Func<>. Behaviors chain through interface dispatch: no closures, no per-behavior allocations. The result: 72 B per Send, whether you have 0, 3, or 5 behaviors. Delegate-wrapping mediators grow linearly with depth.

Two more compile-time perks worth knowing (the rest live in the README):

Exact-type notification dispatch. Publishing DerivedEvent never invokes INotificationHandler<BaseEvent>. No more "why did this handler fire twice" archaeology. It's a deliberate semantic difference from MediatR; know it before migrating.
Build-time diagnostics. The analyzer flags a request with no handler, duplicate handlers, or a mocking library colliding with interceptors while you compile, not at 2 a.m. in production.

The numbers, and how to reproduce them

The question that matters isn't "how fast is Send in a vacuum". It's does the mediator add cost to your actual pipeline? So the headline benchmark is a realistic one: Validation → Logging → Metrics → a simulated async database write (a real async hop via Task.Yield), three behaviors, real DI, each library measured against its own direct-call baseline:

Library	Pipeline latency	Allocated	vs its own direct call
DSoftStudio.Mediator	667 ns	255 B	0.99×
DispatchR 2.1	667 ns	255 B	1.01×
Mediator (Source Gen) 3.0	718 ns	397 B (1.5×)	1.06×
MediatR 14.1	857 ns	1,032 B (3.8×)	1.20×

^{Allocation multiples are each library's ratio vs its own direct-call baseline (~270 B).}

In this pipeline, dispatching through DSoftStudio.Mediator is statistically indistinguishable from calling the code directly (0.99×). The measured cost is the handler's own work, not the dispatch layer.

The micro numbers explain why: pure Send is 7.2 ns / 72 B (direct call: 7.0 ns). With five behaviors: 15.6 ns, still 72 B, while MediatR reaches 153 ns / 1,088 B. Publish is 4.5 ns and zero-alloc. Constant allocation is the property that matters in production: fewer Gen0 collections → tighter p99/p999.

Environment: BenchmarkDotNet 0.15.8, .NET 10, Windows 11, i7-12700F, each library in an isolated process. And here's the only call to action in this post: clone the repo and run the benchmark suite on your own hardware; per-library run scripts are included. Distrust of vendor benchmarks is healthy; that's why they ship with the code.

The DSoftStudio.Mediator companion packages

The core stays lean; integrations are focused MIT packages:

Package	What it does
`DSoftStudio.Mediator.Abstractions`	Contracts only (`netstandard2.0`), with no dependency on the mediator runtime or generators.
`DSoftStudio.Mediator.OpenTelemetry`	Tracing + metrics for `Send`, `Publish`, and `Stream`.
`DSoftStudio.Mediator.FluentValidation`	Automatic request validation as a pipeline behavior.
`DSoftStudio.Mediator.HybridCache`	L1 + L2 response caching via Microsoft's `HybridCache`.

The Abstractions split keeps clean/hexagonal layering honest. The generator runs only in the composition root and discovers handlers across project references:

Host / API      → DSoftStudio.Mediator              (AddMediator + source generator)
Application     → DSoftStudio.Mediator.Abstractions (handlers, requests, behaviors)
Domain          → (no mediator dependency)
Infrastructure  → (no mediator dependency)

Guides for the core and every companion package (installation, CQRS concepts, streaming, Native AOT notes, integrations) live at docs.dsoftstudio.com/mediator, and the project homepage is mediator.dsoftstudio.com.

When you should not use this

It's not a message bus; for cross-process messaging use MassTransit, NServiceBus, or a broker.
It's not an event sourcing framework.
If your design depends on runtime flexibility (inheritance-based notification dispatch, dynamic handler discovery), the compile-time model trades that away by design; weigh that before migrating.
And if you don't need the mediator pattern at all, a direct method call is still the fastest mediator ever written.

That covers the runtime tax. The second tax is one no benchmark can fix: you still can't see the pipeline. Which behaviors wrap each command, where notifications fan out, which component is the slow one, and on which request. Next post in this series: turning the pipeline into something you can navigate, graph, and profile without leaving your IDE.