DEV Community: Shathish

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

Shathish — Wed, 24 Jun 2026 19:58:19 +0000

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

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

Source Generators in .NET: Build Your Own [AutoToString] From Scratch

Shathish — Thu, 11 Jun 2026 20:08:51 +0000

If you've worked with System.Text.Json, Minimal APIs, or Blazor route discovery, you've already benefited from source generators — you just didn't know it. These features all use compile-time code generation under the hood to avoid reflection and deliver faster startup, AOT compatibility, and compile-time safety.

In this series, we'll build source generators from the ground up. By the end, you'll understand how they work, how to write your own, and how to apply the pattern to real-world problems like CQRS handler registration (think Wolverine/MediatR-style pipelines), return type generation, and async/await patterns.

In this first post, we'll start simple: a generator that finds classes marked with [AutoToString] and generates a ToString() override that prints all public properties. No reflection. No runtime cost.

What Is a Source Generator?

A source generator is a component that plugs into the C# compiler (Roslyn). During compilation, it can inspect your code — syntax trees, symbols, attributes — and emit new C# source files that get compiled alongside everything else.

Image credit: Introducing C# Source Generators — .NET Blog

The key constraint: generators add source files. They never modify your existing code. This is a deliberate design choice that keeps the model simple and predictable.

Project Structure

We need two projects:

SourceGenDemo/
├── SourceGenDemo.sln
├── SourceGenDemo.Generator/     ← netstandard2.0 class library
│   ├── SourceGenDemo.Generator.csproj
│   ├── AutoToStringAttributeGenerator.cs
│   └── AutoToStringGenerator.cs
└── SourceGenDemo.App/           ← net10.0 console app
    ├── SourceGenDemo.App.csproj
    ├── Models/
    │   └── Models.cs
    └── Program.cs

The separation matters. The generator is a tool the compiler loads at build time; the app is what actually runs. They have fundamentally different target frameworks and lifecycles.

The Generator Project

The .csproj — This Is Where Most People Get Stuck

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
    <IsRoslynComponent>true</IsRoslynComponent>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.9.2" />
  </ItemGroup>

</Project>

netstandard2.0 is mandatory. This is the single most common mistake. The Roslyn compiler loads generators into its own process, which targets netstandard2.0. If you target net10.0 here, the project compiles fine but the generator silently fails to load. No error, no warning — your generated code just never appears.

EnforceExtendedAnalyzerRules and IsRoslynComponent opt you into stricter analysis rules that catch common generator authoring mistakes at compile time.

Step 1: Ship the Marker Attribute

Before we can find classes decorated with [AutoToString], that attribute needs to exist. A common pattern is to emit it from the generator itself, so consumers don't need a separate shared library:

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Text;
using System.Text;

namespace SourceGenDemo.Generator;

[Generator]
public class AutoToStringAttributeGenerator : IIncrementalGenerator
{
    public const string AttributeSource = """
        // <auto-generated/>
        namespace SourceGenDemo.Attributes;

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

    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        context.RegisterPostInitializationOutput(ctx =>
        {
            ctx.AddSource(
                "AutoToStringAttribute.g.cs",
                SourceText.From(AttributeSource, Encoding.UTF8));
        });
    }
}

RegisterPostInitializationOutput runs unconditionally — it doesn't inspect any user code. It just injects the attribute source into the compilation so the consumer can write using SourceGenDemo.Attributes; without referencing anything extra.

Step 2: The Generator Itself

This is the core. We implement IIncrementalGenerator and set up a three-stage pipeline:

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.CodeAnalysis.Text;
using System.Collections.Immutable;
using System.Linq;
using System.Text;

namespace SourceGenDemo.Generator;

[Generator]
public class AutoToStringGenerator : IIncrementalGenerator
{
    private const string AutoToStringAttributeFullName =
        "SourceGenDemo.Attributes.AutoToStringAttribute";

    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // STEP 1: Syntactic filter — fast, runs on every keystroke
        IncrementalValuesProvider<ClassDeclarationSyntax> classDeclarations =
            context.SyntaxProvider
                .CreateSyntaxProvider(
                    predicate: static (node, _) => IsCandidateClass(node),
                    transform: static (ctx, _) => GetSemanticTarget(ctx))
                .Where(static cls => cls is not null)!;

        // STEP 2: Combine with compilation for symbol resolution
        IncrementalValueProvider<(Compilation, ImmutableArray<ClassDeclarationSyntax>)>
            combined = context.CompilationProvider
                .Combine(classDeclarations.Collect());

        // STEP 3: Generate source
        context.RegisterSourceOutput(combined, static (spc, source) =>
        {
            var (compilation, classes) = source;
            Execute(compilation, classes, spc);
        });
    }

    // ... continued below
}

Let's break down each stage.

The Syntactic Predicate — Keep It Cheap

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

This runs on every syntax node in your entire compilation — potentially thousands of nodes on every keystroke in the IDE. It must be trivially fast. No semantic model access, no LINQ, no allocations. We're just asking: "Is this a class declaration with at least one attribute?" That's it.

The Semantic Transform — Verify the Attribute

private static ClassDeclarationSyntax? GetSemanticTarget(
    GeneratorSyntaxContext context)
{
    var classDecl = (ClassDeclarationSyntax)context.Node;
    var model = context.SemanticModel;

    foreach (var attributeList in classDecl.AttributeLists)
    {
        foreach (var attribute in attributeList.Attributes)
        {
            var symbol = model.GetSymbolInfo(attribute).Symbol?.ContainingType;
            if (symbol?.ToDisplayString() == AutoToStringAttributeFullName)
                return classDecl;
        }
    }

    return null;
}

This only runs on nodes that passed the syntactic filter. Now we can afford to use the semantic model. We resolve the attribute's actual type symbol and compare the fully qualified name. This prevents false positives — if someone has a completely different [AutoToString] attribute in another namespace, we won't accidentally match it.

The difference between syntax and semantics here is important: syntax tells you "there's a class with an attribute called AutoToString"; the semantic model tells you "that attribute resolves to this specific type in this compilation."

The Execution — Emit Source

private static void Execute(
    Compilation compilation,
    ImmutableArray<ClassDeclarationSyntax> classes,
    SourceProductionContext context)
{
    if (classes.IsDefaultOrEmpty)
        return;

    var distinctClasses = classes.Distinct();

    foreach (var classDecl in distinctClasses)
    {
        var model = compilation.GetSemanticModel(classDecl.SyntaxTree);
        if (model.GetDeclaredSymbol(classDecl) is not INamedTypeSymbol classSymbol)
            continue;

        var namespaceName = classSymbol.ContainingNamespace.IsGlobalNamespace
            ? null
            : classSymbol.ContainingNamespace.ToDisplayString();

        var className = classSymbol.Name;

        var properties = classSymbol
            .GetMembers()
            .OfType<IPropertySymbol>()
            .Where(p => p.DeclaredAccessibility == Accessibility.Public
                     && !p.IsStatic
                     && !p.IsIndexer)
            .ToList();

        var sb = new StringBuilder();
        sb.AppendLine("// <auto-generated/>");
        sb.AppendLine();

        if (namespaceName is not null)
        {
            sb.AppendLine($"namespace {namespaceName};");
            sb.AppendLine();
        }

        sb.AppendLine($"public partial class {className}");
        sb.AppendLine("{");
        sb.AppendLine("    public override string ToString()");
        sb.AppendLine("    {");

        if (properties.Count == 0)
        {
            sb.AppendLine($"        return \"{className} {{ }}\";");
        }
        else
        {
            sb.Append($"        return $\"{className} {{{{ ");

            for (int i = 0; i < properties.Count; i++)
            {
                var prop = properties[i];
                sb.Append($"{prop.Name} = {{{prop.Name}}}");
                if (i < properties.Count - 1)
                    sb.Append(", ");
            }

            sb.AppendLine(" }}}}\";");
        }

        sb.AppendLine("    }");
        sb.AppendLine("}");

        context.AddSource(
            $"{className}_AutoToString.g.cs",
            SourceText.From(sb.ToString(), Encoding.UTF8));
    }
}

A few things to call out:

The class must be partial. We're emitting a second partial declaration with the ToString() override. If the original class isn't partial, the compiler sees two conflicting definitions and errors.
We deduplicate. A class might appear multiple times if it has multiple attribute lists or partial declarations.
The {{{{ brace escaping. This trips everyone up. Our generator code uses $"" interpolation, and the output is also an interpolated string. So braces go through two levels of interpretation: {{{{ in the generator → {{ in the generated file → { at runtime. Get this wrong and you'll see CS1073/CS1525 errors pointing at your generated files.

The Consumer Project

The .csproj — Two Magic Properties

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference
      Include="..\SourceGenDemo.Generator\SourceGenDemo.Generator.csproj"
      OutputItemType="Analyzer"
      ReferenceOutputAssembly="false" />
  </ItemGroup>

</Project>

OutputItemType="Analyzer" tells the compiler to load this project as an analyzer/generator.
ReferenceOutputAssembly="false" means the app doesn't reference the generator DLL at runtime — it's a build-time-only dependency.

Without both of these, the compiler treats the generator as a normal project reference and your generator never runs. Like the netstandard2.0 requirement, there's no helpful error message. It just silently doesn't work.

The Models

using SourceGenDemo.Attributes;

namespace SourceGenDemo.App.Models;

[AutoToString]
public partial class Product(string name, decimal price, string category)
{
    public string Name { get; set; } = name;
    public decimal Price { get; set; } = price;
    public string Category { get; set; } = category;

    private string _internalCode = "SKU-001";
}

[AutoToString]
public partial class Customer(string firstName, string lastName, string email)
{
    public string FirstName { get; set; } = firstName;
    public string LastName { get; set; } = lastName;
    public string Email { get; set; } = email;
    public int LoyaltyPoints { get; set; }
}

// No [AutoToString] — the generator ignores this.
public class Order
{
    public int Id { get; set; }
    public decimal Total { get; set; }
}

Notice partial on both decorated classes. The private _internalCode field on Product won't appear in the generated ToString() because our generator only collects public properties.

Program.cs

using SourceGenDemo.App.Models;

var product = new Product("Mechanical Keyboard", 149.99m, "Electronics");

var customer = new Customer("Adolphous", "Dev", "adolphous@example.com")
{
    LoyaltyPoints = 4200
};

Console.WriteLine(product);
Console.WriteLine(customer);

// Falls through to default Object.ToString()
var order = new Order { Id = 1, Total = 299.98m };
Console.WriteLine(order);

Output

Product { Name = Mechanical Keyboard, Price = 149.99, Category = Electronics }
Customer { FirstName = Adolphous, LastName = Dev, Email = adolphous@example.com, LoyaltyPoints = 4200 }
SourceGenDemo.App.Models.Order

The Order line shows the default Object.ToString() since it doesn't have the attribute.

Inspecting the Generated Code

Add this to the consumer's .csproj:

<PropertyGroup>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

After building, check obj/Debug/net10.0/generated/SourceGenDemo.Generator/. You'll see files like Product_AutoToString.g.cs:

// <auto-generated/>

namespace SourceGenDemo.App.Models;

public partial class Product
{
    public override string ToString()
    {
        return $"Product {{ Name = {Name}, Price = {Price}, Category = {Category} }}";
    }
}

This is real, inspectable C# that the compiler treats exactly like hand-written code. You can set breakpoints in it, navigate to it with "Go to Definition", and see it in your IDE's generated files node.

The Gotchas That Will Waste Your Afternoon

Let me save you some debugging time. These are the non-obvious failure modes, ranked by how silently they fail:

Generator targets anything other than netstandard2.0 — compiles, loads, generates nothing. No error.
Missing OutputItemType="Analyzer" on the project reference — compiles, generator never invoked. No error.
Consumer class isn't partial — you get a compiler error, but it points at the generated file, which can be confusing if you don't know generated files exist yet.
Using ISourceGenerator instead of IIncrementalGenerator — works, but re-runs your generator on every single keystroke in the IDE. For a small generator it's fine; for anything touching the semantic model across many files, it tanks IDE performance.
Brace escaping in generated interpolated strings — { in your generator's $"" becomes a literal brace in the output, but if the output is also an interpolated string, you need {{{{ to get a literal brace at runtime. Expect CS1073/CS1525 errors if you get this wrong.

Why `IIncrementalGenerator` Over `ISourceGenerator`?

The older ISourceGenerator interface has a simple Execute method that receives the entire compilation. Simple, but the compiler has to re-run it from scratch whenever anything changes. The incremental pipeline we built (predicate → transform → output) lets the compiler cache intermediate results. If you edit Program.cs, the generator doesn't re-process Product and Customer because their syntax trees haven't changed.

For a two-class demo this doesn't matter. For a generator running across a 500-file solution in VS, it's the difference between instant feedback and a frozen IDE.

What's Next

This covers the foundation: project structure, the incremental pipeline, attribute discovery, and source emission. In the next post, we'll build something more practical — a source generator that automatically discovers and registers CQRS command/query handlers, similar to how Wolverine and MediatR find handlers at startup, but shifted entirely to compile time.

This is Part 1 of the Source Generators in .NET series. Follow along for the next post on CQRS handler auto-registration.

DEV Community: Shathish

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

What We're Building Toward

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

The Data Model: HandlerInfo

Building the Generator

Injecting the Attribute

Finding Handlers — and What Their Handle Method Accepts

Gathering Every Handler Into One File

Writing the Switch Table

Seeing It Work

The Full Incremental Picture

Gotchas, Ranked by How Quietly They Fail

What's Next

Source Generators in .NET: Build Your Own [AutoToString] From Scratch

What Is a Source Generator?

Project Structure

The Generator Project

The .csproj — This Is Where Most People Get Stuck

Step 1: Ship the Marker Attribute

Step 2: The Generator Itself

The Syntactic Predicate — Keep It Cheap

The Semantic Transform — Verify the Attribute

The Execution — Emit Source

The Consumer Project

The .csproj — Two Magic Properties

The Models

Program.cs

Output

Inspecting the Generated Code

The Gotchas That Will Waste Your Afternoon

Why IIncrementalGenerator Over ISourceGenerator?

What's Next

The Data Model: `HandlerInfo`

Finding Handlers — and What Their `Handle` Method Accepts

Why `IIncrementalGenerator` Over `ISourceGenerator`?