Source Generators in .NET: Build a Zero-Reflection Command Dispatcher

In Part 1, we built a generator that found classes marked [AutoToString] and emitted a ToString() override for them. It was a good first generator precisely because it didn't have much else going on — find a class, check an attribute, write a file. This time we're pointing the same incremental pipeline at something with more architectural payoff: a command dispatcher.

Most dispatchers — MediatR, a hand-rolled one, whatever you've used — resolve handlers at runtime. They scan assemblies, walk type hierarchies, hit a dictionary or a service locator to figure out which handler runs which command. That works, but it costs reflection at startup, allocations you can't see, and errors that only show up when the app is already running.

What if the dispatcher was just a switch statement? One the compiler wrote for you, based on whatever handlers actually exist in your project?

That's what we're building. By the end, a class decorated with [RegisterHandler] will get picked up automatically, and dispatching a command will look like an ordinary method call — no reflection, no container, just a generated switch.

What We're Building Toward

// <auto-generated />
namespace MySourceGenerator;

public partial class InlineDispatcher
{
    public void Dispatch(object command)
    {
        if (command is null) return;

        switch (command)
        {
            case MyApp.Commands.CreateUserCommand cmd:
                new MyApp.Handlers.CreateUserHandler().Handle(cmd);
                break;

            default:
                throw new InvalidOperationException(
                    $"No handler registered for command type: {command.GetType().FullName}.");
        }
    }
}

Every case arm in that file was written by a generator. You never touch it — add a new handler, rebuild, and a new case shows up.

The project setup is identical to Part 1: generator project on netstandard2.0, referenced with OutputItemType="Analyzer" and ReferenceOutputAssembly="false", same syntax-then-semantics pipeline shape. I won't re-walk that part — if it's unfamiliar, that's what Part 1 covers. What's new here is everything specific to dispatching: carrying structured data through the pipeline instead of a bare syntax node, and aggregating many classes into one generated file instead of one file per class.

A Small Wrinkle Before We Start: Records on netstandard2.0

The generator is going to lean on a record to carry data between pipeline stages (more on why in a moment). Records need init-only setters, which rely on System.Runtime.CompilerServices.IsExternalInit under the hood — a type that exists in .NET 5+ but not in netstandard2.0. And the generator project is stuck on netstandard2.0 no matter what <LangVersion> you set.

The fix is one of those one-line shims that's annoying to discover and trivial once you know it:

// IsExternalInit.cs — inside the generator project
namespace System.Runtime.CompilerServices
{
    internal static class IsExternalInit { }
}

Declaring this empty class satisfies the compiler without needing the real runtime type. You'll see this exact polyfill in most generator projects that use records or init — it's a known trick, not a hack you invented.

The Data Model: HandlerInfo

Part 1's generator never needed to carry data between pipeline stages — it found a class, checked an attribute, and emitted a file right there. A dispatcher is different: we need to gather information about every handler in the project before we can write a single switch statement. That means defining a small data model to carry through the pipeline:

namespace LightweightDispatcher.Generator;

public record HandlerInfo(string CommandType, string HandlerType);

Just two fully-qualified type names. But the choice of record over class, and string over a Roslyn symbol, isn't incidental — both decisions are load-bearing.

It's a record, not a class, because the incremental pipeline caches results between runs by comparing outputs for equality. Records give you structural equality for free — two HandlerInfo instances with the same strings are equal, full stop. A plain class compares by reference, so Roslyn would conclude every run produced "new" data and re-run everything downstream — which defeats the entire point of using IIncrementalGenerator in the first place.

It stores strings, not INamedTypeSymbol, because Roslyn symbols are tied to a specific compilation snapshot. Hold onto one across pipeline stages and you've got a memory leak and broken caching waiting to happen. The rule here is absolute: never store a Roslyn symbol in a pipeline data model. Pull out what you need as a string immediately, and carry that instead.

Building the Generator

[Generator]
public sealed class DispatcherGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // ...
    }
}

sealed because there's no reason to subclass a generator. Initialize runs exactly once, at load time — its job is to describe the pipeline, not run it. The actual scanning and emitting happens lazily, driven by Roslyn, every time something relevant changes.

Injecting the Attribute

Same trick as Part 1: before any user code is analyzed, inject the marker attribute so it exists in the compilation without the consumer needing a separate package.

context.RegisterPostInitializationOutput(static postInitContext =>
{
    const string attribSource = @"
        namespace MySourceGenerator;

        [System.AttributeUsage(System.AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
        public sealed class RegisterHandlerAttribute : System.Attribute
        {
        }
    ";

    postInitContext.AddSource("RegisterHandlerAttribute.g.cs", attribSource);
});

AllowMultiple = false means a class can only carry one [RegisterHandler]. Inherited = false means it doesn't flow down to subclasses — each handler has to opt in explicitly.

Notice the static on that lambda. It's not a style preference — it's enforced statelessness. Generators have to be stateless between runs; an accidental closure over this or a captured local is exactly the kind of thing that silently breaks Roslyn's caching without throwing an error anywhere.

Finding Handlers — and What Their Handle Method Accepts

The syntax-then-semantics shape is the same two-phase filter from Part 1: a cheap predicate runs on every node in the compilation, and only survivors get the expensive semantic treatment.

var classesWithAttributes = context.SyntaxProvider.CreateSyntaxProvider(
        predicate: static (node, _) => IsClassWithAttributes(node),
        transform: static (ctx, _) => GetSemanticTargetForGeneration(ctx))
    .Where(static target => target is not null);

private static bool IsClassWithAttributes(SyntaxNode node)
    => node is ClassDeclarationSyntax { AttributeLists.Count: > 0 };

Where it gets more interesting is the semantic transform. Part 1's version only had to answer "does this attribute resolve to the right type?" This one has to go further — once it confirms the attribute, it has to dig into the class and find out what command type its Handle method actually accepts:

private static HandlerInfo? GetSemanticTargetForGeneration(GeneratorSyntaxContext context)
{
    var classDecl = (ClassDeclarationSyntax)context.Node;

    foreach (var attributeList in classDecl.AttributeLists)
    {
        foreach (var attribute in attributeList.Attributes)
        {
            if (context.SemanticModel.GetSymbolInfo(attribute).Symbol
                    is not IMethodSymbol attributeConstructor)
                continue;

            var attributeType = attributeConstructor.ContainingType;

            if (attributeType.ToDisplayString() == "MySourceGenerator.RegisterHandlerAttribute")
            {
                var handlerSymbol = context.SemanticModel
                    .GetDeclaredSymbol(classDecl) as INamedTypeSymbol;

                if (handlerSymbol is null) return null;

                var handleMethod = handlerSymbol.GetMembers("Handle")
                    .OfType<IMethodSymbol>()
                    .FirstOrDefault();

                if (handleMethod is not null && handleMethod.Parameters.Length == 1)
                {
                    var commandFullName = handleMethod.Parameters[0].Type.ToDisplayString();
                    var handlerFullName = handlerSymbol.ToDisplayString();
                    return new HandlerInfo(commandFullName, handlerFullName);
                }
            }
        }
    }

    return null;
}

A detail that's easy to walk past: GetSymbolInfo(attribute).Symbol hands back an IMethodSymbol, not the attribute type itself. Applying an attribute is, under the hood, a constructor call — so the symbol you get back is that constructor, and you reach the attribute's type via .ContainingType. It's a small thing, but it's the reason the pattern match is written the way it is.

Once the attribute checks out, the method goes looking for a Handle method on the class and reads the type of its single parameter. That parameter type — fully qualified, via ToDisplayString() — is the command type. Pair it with the handler's own fully qualified name, and that's everything the dispatcher needs to know about this one handler.

Gathering Every Handler Into One File

This is where the shape genuinely diverges from Part 1. The AutoToString generator emitted one file per matching class, completely independently of every other class. A dispatcher can't work that way — every handler's case has to land in the same file, because there's only one switch statement.

IncrementalValueProvider<ImmutableArray<HandlerInfo?>> gatheredHandlers =
    classesWithAttributes.Collect();

context.RegisterSourceOutput(gatheredHandlers, static (productionContext, handlers) =>
{
    var generatedCode = GenerateDispatcherSource(handlers);
    productionContext.AddSource("InlineDispatcher.g.cs", generatedCode);
});

Before .Collect(), classesWithAttributes is a stream — one HandlerInfo? per matching class, each independent. .Collect() folds that stream into a single ImmutableArray holding every result at once. That's the signal for when to reach for it: use .Collect() when the output genuinely depends on all the matches together, and skip it when each match can produce its own output in isolation, the way Part 1's classes did.

Writing the Switch Table

private static string GenerateDispatcherSource(ImmutableArray<HandlerInfo?> handlers)
{
    var switchCases = new System.Text.StringBuilder();

    foreach (var handler in handlers)
    {
        if (handler is null) continue;

        switchCases.AppendLine($@"            case {handler.CommandType} cmd:");
        switchCases.AppendLine($@"                new {handler.HandlerType}().Handle(cmd);");
        switchCases.AppendLine($@"                break;");
    }

    return $$"""
             // <auto-generated />
             namespace MySourceGenerator;

             public partial class InlineDispatcher
             {
                 public void Dispatch(object command)
                 {
                     if (command is null) return;

                     switch (command)
                     {
                        {{switchCases}}
                         default:
                             throw new System.InvalidOperationException(
                                 $"No handler registered for command type: {command.GetType().FullName}.");
                     }
                 }
             }
             """;
}

Part 1 ran into the brace-escaping problem head-on — {{{{ to push one literal { through two layers of string interpolation. This generator sidesteps it entirely with a raw string literal using a custom delimiter: $$"""...""". With the double-dollar prefix, only {{...}} triggers interpolation; single { and } are just characters. The whole switch block's native braces can sit there untouched. Same underlying problem as Part 1, cleaner tool for it.

Two things worth a second look in the generated code itself:

• case CommandType cmd: is a type-pattern switch. Inside that case body, cmd is already typed as the specific command — Handle(cmd) needs no cast.
• new {handler.HandlerType}().Handle(cmd) constructs the handler directly with new. No container, no factory — which is exactly the "lightweight" part of the name, and exactly the thing we'll outgrow once handlers need constructor dependencies.

partial is doing a different job here than it did in Part 1. There, it let the generator bolt a method onto a class you'd written. Here, the generator owns InlineDispatcher outright — partial just leaves the door open for you to add fields or constructors to it in your own file, without ever touching the generated one.

Seeing It Work

Here's a small console app wired up against the generator, with two handlers:

// Commands.cs
namespace MyApp.Commands;

public record CreateUserCommand(string Username);
public record DeactivateUserCommand(int UserId);

// Handlers.cs
using MySourceGenerator;
using MyApp.Commands;

namespace MyApp.Handlers;

[RegisterHandler]
public class CreateUserHandler
{
    public void Handle(CreateUserCommand command)
        => Console.WriteLine($"Creating user '{command.Username}'");
}

[RegisterHandler]
public class DeactivateUserHandler
{
    public void Handle(DeactivateUserCommand command)
        => Console.WriteLine($"Deactivating user #{command.UserId}");
}

// No [RegisterHandler] — the dispatcher won't know about this one.
public class AuditLogger
{
    public void Handle(CreateUserCommand command)
        => Console.WriteLine("This never runs — not registered.");
}

// Program.cs
using MyApp.Commands;
using MySourceGenerator;

var dispatcher = new InlineDispatcher();

dispatcher.Dispatch(new CreateUserCommand("adolphous"));
dispatcher.Dispatch(new DeactivateUserCommand(42));

try
{
    dispatcher.Dispatch("not a command");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Caught: {ex.Message}");
}

Output:

Creating user 'adolphous'
Deactivating user #42
Caught: No handler registered for command type: System.String.

InlineDispatcher never existed as a file you wrote. Add a third [RegisterHandler] class tomorrow, rebuild, and a third case shows up in it with no further wiring. Drop the attribute from a handler, like AuditLogger above, and the generator simply never sees it — no error, no case, no dispatch.

If you add <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> to the app's .csproj like we did in Part 1, the generated file under obj/Debug/net10.0/generated/.../InlineDispatcher.g.cs looks exactly like the target we sketched out at the start of this post — just with both case arms filled in.

The Full Incremental Picture

Roslyn parses .cs files → SyntaxTrees

PostInitializationOutput (once, cached)
→ injects RegisterHandlerAttribute.g.cs

SyntaxProvider walks every SyntaxNode
→ Predicate: IsClassWithAttributes          [syntax only, runs on everything]
→ Transform: GetSemanticTargetForGeneration [semantic, runs on survivors]
→ .Where(not null)                          [drops non-matching classes]
→ .Collect()                                [gathers into ImmutableArray]

RegisterSourceOutput
→ GenerateDispatcherSource builds the switch table
→ AddSource injects InlineDispatcher.g.cs

Roslyn compiles: user code + attribute file + dispatcher file

Edit some unrelated file and rebuild, and Roslyn re-runs the predicate, gets the same passing nodes, the transform produces HandlerInfo records that are structurally equal to last time, .Collect() produces an identical array — and RegisterSourceOutput never fires. The dispatcher file from the previous build is reused untouched. That's the entire reason the record choice mattered earlier: without value equality, every build would look "changed," and the caching shown in this diagram wouldn't happen at all.

Gotchas, Ranked by How Quietly They Fail

1. Using a plain class instead of a record for pipeline data. Compiles fine, generator runs fine — it just re-emits on every build instead of caching, and you won't notice unless you're watching build times or IDE responsiveness.
2. Forgetting the IsExternalInit polyfill when a pipeline model uses record or init. This one isn't quiet — it's a hard compile error on the generator project — but it's a confusing one if you don't already know netstandard2.0 is missing the type.
3. Holding an INamedTypeSymbol (or any ISymbol) in a data model that survives past a single pipeline stage. No immediate error. Just memory growth and caching that mysteriously stops working as the project grows.
4. Reaching for .Collect() on output that didn't need aggregating. Not wrong, exactly — but it forces every downstream emission to re-run whenever any single handler changes, instead of only the one that actually changed.
5. A handler class without a Handle method, or with the wrong parameter count. GetSemanticTargetForGeneration just returns null for it — same as a class that never had [RegisterHandler] in the first place. No warning, no case in the switch, nothing dispatched. Worth an analyzer in its own right, but that's outside the scope of this post.

What's Next

This dispatcher works, but it instantiates handlers with new, which rules out constructor dependencies entirely. In the next post — the last in this trio — we'll build a generator that scans for IHandler<TCommand> implementations instead of an attribute, resolves handlers via IServiceProvider, and emits an AddLightweightDispatcher() DI registration extension alongside the dispatcher itself.