C# Source Generators — Silent Failure After .NET 8 Update

Every non-trivial C# codebase eventually drowns in boilerplate. You've written the same INotifyPropertyChanged implementation fifteen times. You've hand-rolled JSON serialization methods that drift out of sync with your models. You've copy-pasted mapping code between domain objects and DTOs until maintaining it felt like archaeology. The problem isn't laziness — it's that the language used to give you no good alternative between writing it yourself and paying the runtime cost of reflection or dynamic code generation.

Source Generators, introduced in .NET 5 and significantly improved through .NET 6, 7, and 8 with Incremental Generators, solve this at the right layer: compile time. Instead of generating code while your application runs and slowing down startup, or using T4 templates that live outside the build pipeline and break silently, Source Generators are first-class Roslyn components. They receive a full semantic model of your code, produce new C# source files, and those files are compiled into your assembly as if you wrote them yourself. Zero runtime overhead. Full IntelliSense. Full debuggability.

By the end of this article you'll understand how the Roslyn compilation pipeline hands control to your generator, how to build both a basic ISourceGenerator and the modern IIncrementalGenerator, how to handle real-world scenarios like caching, diagnostics, and multi-targeting, and — critically — the production gotchas that will bite you if you skip them. You'll walk away able to write a production-grade generator and explain it confidently in an interview.

What Are C# Source Generators?

Source Generators are components that plug into the Roslyn compiler pipeline. They receive the full compilation object — syntax trees, semantic model, references — and produce additional source files that become part of the same compilation. Unlike code generation tools that run as a separate build step (T4, custom MSBuild tasks), generators run inside the compiler. That means they have access to type information, can read attributes, and can produce code that the compiler type-checks in the same pass.

The magic happens around the CompilationUnit stage: after the compiler parses all files and binds symbols, it invokes registered generators before emitting IL. The generated files are merged into the compilation as if they were written by hand. No post-processing, no second compilation step.

The key distinction: you should never generate code that could be written as a direct method call or a generic. Generators shine when code must be repeated across types that can't share a common base class, or when the pattern depends on metadata unavailable at the generic level.

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

namespace io.thecodeforge.generators
{
    [Generator(LanguageVersion.CSharp12)]
    public sealed class HelloWorldGenerator : IIncrementalGenerator
    {
        public void Initialize(IncrementalGeneratorInitializationContext context)
        {
            // Register a pipeline that produces a single constant source file
            context.RegisterSourceOutput(context.CompilationProvider,
                (spc, compilation) =>
                {
                    string source = @"// <auto-generated/>
namespace io.thecodeforge
{
    public static class Greeter
    {
        public static string Hello() => ""Hello from a Source Generator!"";
    }
}";
                    spc.AddSource("Greeter.g.cs", SourceText.From(source, Encoding.UTF8));
                });
        }
    }
}

Building an Incremental Generator Pipeline

An incremental generator consists of a pipeline of steps. Each step takes an input (like a SyntaxNode or SemanticModel) and produces a value. The framework caches these values using equality comparers you provide. When a source file changes, only the affected pipeline branches re-execute.

The pipeline starts in the Initialize method where you register sources of data: CompilationProvider, SyntaxProvider, etc. The SyntaxProvider filters syntax nodes (e.g., all classes with a specific attribute). Then you transform those nodes into your model (like a DTO description), combine with the compilation, and finally register the source output.

Here's a real example that generates a TypeScript-like partial class for INotifyPropertyChanged without using reflection at runtime.

[Generator(LanguageVersion.CSharp12)]
public sealed class NotifyPropertyChangedGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // Step 1: Find all classes with [GenerateNotify] attribute
        IncrementalValuesProvider<ClassDeclarationSyntax> classDeclarations = context.SyntaxProvider
            .CreateSyntaxProvider(
                predicate: (node, _) => node is ClassDeclarationSyntax cds &&
                    cds.AttributeLists.Count > 0,
                transform: (ctx, _) => ctx.Node as ClassDeclarationSyntax)
            .Where(c => c is not null)!;

        // Step 2: For each class, extract property info using semantic model
        IncrementalValuesProvider<NotifyModel> models = classDeclarations
            .Select((cds, ct) => ExtractModel(cds, ct));

        // Step 3: Combine and register output
        context.RegisterSourceOutput(models,
            (spc, model) => GeneratePartialClass(spc, model));
    }

    private NotifyModel ExtractModel(ClassDeclarationSyntax cds, CancellationToken ct)
    {
        return new NotifyModel(cds.Identifier.Text);
    }

    private void GeneratePartialClass(SourceProductionContext spc, NotifyModel model)
    {
        string source = $"""
// <auto-generated/>
partial class {model.ClassName} : INotifyPropertyChanged
{{
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged([CallerMemberName] string name = null)
        => PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}}
""";
        spc.AddSource($"{model.ClassName}.g.cs", SourceText.From(source, Encoding.UTF8));
    }

    private readonly record struct NotifyModel(string ClassName);
}

Real-World Patterns: DTO Generation, Auto-Mapping, and Serialization

The most practical use of source generators is eliminating boilerplate that would otherwise require runtime reflection or code duplication. Three patterns dominate production code:

1. DTO Generation from database models – Generate DTO classes with the same properties as your EF Core entities, automatically adding JsonPropertyName attributes from column names.
2. Auto-Mapping – Generate extension methods that map object A to object B based on matching property names and types. No reflection, no slow runtime map building.
3. Serialization helpers – Generate custom JSON serializers for specific types that avoid the overhead of System.Text.Json's reflection fallback. A source generator can produce highly optimised serialization code that outperforms the built-in serialiser by 2-3x for known types.

The pattern in all three is the same: decorate a type or member with an attribute, then the generator reads that attribute and produces the corresponding code. The generated code is a regular C# file that you can inspect and debug.

// Example: [GenerateDto(SourceType = typeof(Entity))]
// Generates: EntityDto with same properties plus [JsonIgnore] for navigation properties

[AttributeUsage(AttributeTargets.Class)]
public sealed class GenerateDtoAttribute : Attribute
{
    public Type SourceType { get; set; }
}

// In generator pipeline:
private IEnumerable<(string Name, ITypeSymbol Type, bool IsNav)> GetProperties(INamedTypeSymbol entity)
{
    foreach (var member in entity.GetMembers())
    {
        if (member is IPropertySymbol prop && !prop.IsStatic)
        {
            yield return (prop.Name, prop.Type,
                prop.Type.TypeKind == TypeKind.Class &&
                prop.Type.SpecialType != SpecialType.System_String);
        }
    }
}

Production Pitfalls and How to Avoid Them

Source generators are powerful but they come with unique production traps. Here are the ones that bite even experienced teams:

Pitfall 1: The generator runs in a partial compilation context. You cannot call System.IO.File.ReadAllText inside a generator without first registering the file as an additional file in the csproj. The generator host restricts I/O for security and determinism.

Pitfall 2: Error reporting is silent by default. If your generator throws an unhandled exception, the build may succeed with a warning. You must report errors explicitly via context.ReportDiagnostic(Diagnostic.Create(...)).

Pitfall 3: Multi-targeting confusion. If your library targets multiple frameworks, the generator must be conditionally included only for netstandard2.0 (since it runs on the analyzer host). The generated code must also be compatible with the target framework — you can't use C# 12 syntax in code deployed to .NET Framework 4.6.1.

Pitfall 4: Assembly versioning. Generated code lives in the consuming assembly. If you update the generator package, old generated files are not automatically invalidated. Use incremental generators with versioned pipeline inputs to force regeneration when the generator version changes.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>12</LangVersion>
    <EnforceAnalyzer>true</EnforceAnalyzer>
    <IncludeBuildOutput>false</IncludeBuildOutput>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.10.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" PrivateAssets="all" />
  </ItemGroup>
</Project>

When Not to Use Source Generators

Source generators are not the right tool for every problem. They add complexity to the build process and increase assembly size. Avoid them in these scenarios:

• Simple runtime polymorphism – If a regular interface or abstract class solves the problem, don't bring a generator.
• Dynamic code that changes during runtime – Generators are compile-time only. Use Reflection.Emit or System.Linq.Expressions.
• Cross-cutting logging or tracing – Use a runtime AOP framework like Castle DynamicProxy or the .NET interceptors pattern instead of generating wrapper classes for every method.
• Small projects – The setup overhead of a generator project, package dependency, and build caching complexity is not justified for a single DTO mapping.

A good heuristic: if you can solve the problem with a generic type and a few interfaces, do that first. Only reach for a generator when the pattern repeats across unrelated types and the alternative would be runtime reflection or hand-written copy-paste.

// Use a source generator if:
// - You need INotifyPropertyChanged on every model class
// - You generate custom JSON serializers for sealed types
// - You auto-register MediatR handlers based on marker interfaces

// Do NOT use a source generator for:
// - Simple mapping between two known types (write a method)
// - Logging around every method call (use DynamicProxy or interceptors)
// - Runtime code generation based on configuration files

public interface ICommand { }
public class CreateOrderCommand : ICommand { }

// This is overkill for a single command.
// A generated handler registration is unnecessary.

How Source Generators Actually Work — The Compiler Pipeline

Stop thinking of Source Generators as magic. They're a compiler plugin. The Roslyn compiler parses your code into a syntax tree, runs semantic analysis, then hands that tree to your generator. Your generator walks the tree, extracts metadata, and spits out new syntax trees — which the compiler merges back in before emitting IL.

That's it. No runtime reflection. No IL weaving at build time. No post-compilation hacks. The generated code is first-class citizen from the start. If your generator throws, the build fails. If your generated code has a syntax error, the compiler tells you before it ever runs.

The critical detail most tutorials skip: generators run in an incremental pipeline. The compiler doesn't re-run your generator on every keystroke. It caches previous results and recomputes only when relevant input changes. That's why you implement IIncrementalGenerator, not the old ISourceGenerator. The old API kills IDE performance. The incremental API is mandatory for production use.

Your generator receives a SourceProductionContext and a pipeline of IncrementalValueProvider or IncrementalValuesProvider. These providers carry the syntax trees, compilation, or custom data you extract. Every generation step must be deterministic and side-effect free. No file I/O. No database calls. If you break that rule, the compiler can't cache your results, and your build time explodes.

// io.thecodeforge — csharp tutorial

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;

// Production rule: never use ISourceGenerator.
// Implement IIncrementalGenerator or your team will hate you.
[Generator(LanguageNames.CSharp)]
public sealed class EnumExtensionsGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // Filter for enum declarations only — don't scan every node
        IncrementalValuesProvider<EnumDeclarationSyntax> enumDeclarations =
            context.SyntaxProvider.CreateSyntaxProvider(
                predicate: (node, _) => node is EnumDeclarationSyntax,
                transform: (ctx, _) => (EnumDeclarationSyntax)ctx.Node)
            .Where(static e => e is not null);

        // Only re-run when an enum definition actually changes
        IncrementalValueProvider<(Compilation, ImmutableArray<EnumDeclarationSyntax>)> combined =
            context.CompilationProvider.Combine(enumDeclarations.Collect());

        context.RegisterSourceOutput(combined, GenerateSource);
    }

    private void GenerateSource(
        SourceProductionContext context,
        (Compilation Compilation, ImmutableArray<EnumDeclarationSyntax> Enums) source)
    {
        // generation logic here
    }
}

Getting Started — Your First Generator Without the Fluff

Forget the "Hello World" that prints nothing. Here's the real deal: a generator that creates strongly-typed enum extensions. You need three projects: a .NET standard library for the generator, the generator project itself (targeting netstandard2.0 — not negotiable), and a consuming project that references both.

Why netstandard2.0? Because Source Generators run during compilation, not at runtime. The compiler runs on .NET Framework or .NET Core. If you target anything newer, the compiler can't load your assembly. This is the #1 mistake beginners make.

Set up your `.csproj` like this: <Project Sdk="Microsoft.NET.Sdk"> with <TargetFramework>netstandard2.0</TargetFramework>. Add the Microsoft.CodeAnalysis.CSharp and Microsoft.CodeAnalysis.Analyzers NuGet packages. That's it. No special analysis-level config. No <IsRoslynComponent> flag — that's an Analyzer thing, not a Generator thing.

Now write your generator class. It must implement IIncrementalGenerator and be decorated with [Generator]. The Initialize method sets up your pipeline. For a first pass, just grab all enum declarations and emit a partial class with a ToDisplayString() method that returns the enum name via reflection — no, that's stupid. Actually generate a switch expression. Compile-time resolution, zero reflection overhead.

Test your generator by adding a reference in your consuming project. Build. If no new files appear, check the error list. The C# compiler will tell you exactly what broke.

// io.thecodeforge — csharp tutorial

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System.Text;

[Generator(LanguageNames.CSharp)]
public sealed class EnumExtensionsGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var enums = context.SyntaxProvider.CreateSyntaxProvider(
            static (node, _) => node is EnumDeclarationSyntax,
            static (ctx, _) => (EnumDeclarationSyntax)ctx.Node
        ).Where(static e => e is not null);

        var compilationAndEnums = context.CompilationProvider.Combine(enums.Collect());

        context.RegisterSourceOutput(compilationAndEnums, (spContext, source) =>
        {
            var (compilation, enumList) = source;
            foreach (var enumDecl in enumList)
            {
                var model = compilation.GetSemanticModel(enumDecl.SyntaxTree);
                if (model.GetDeclaredSymbol(enumDecl) is not INamedTypeSymbol symbol)
                    continue;

                var ns = symbol.ContainingNamespace?.ToDisplayString() ?? "";
                var name = symbol.Name;
                var members = enumDecl.Members
                    .Select(m => m.Identifier.Text)
                    .ToList();

                var sb = new StringBuilder();
                sb.AppendLine($$"""
                // <auto-generated/>
                namespace {{ns}}
                {
                    public static class {{name}}Extensions
                    {
                        public static string ToDisplayString(this {{name}} value) =>
                """);

                sb.AppendLine("            value switch");
                sb.AppendLine("            {");
                foreach (var member in members)
                {
                    sb.AppendLine($"                {{name}}.{member} => \"{member}\",");
                }
                sb.AppendLine("                _ => throw new ArgumentOutOfRangeException(nameof(value))");
                sb.AppendLine("            };");
                sb.AppendLine("    }");
                sb.AppendLine("}");

                spContext.AddSource($"{name}Extensions.g.cs", sb.ToString());
            }
        });
    }
}

Practical Use Case: INotifyPropertyChanged Without Pain

You've seen the INotifyPropertyChanged pattern. You've cursed the boilerplate. Here's how Source Generators kill it dead.

Problem: you have a ViewModel with 15 properties. Each property needs a backing field, a getter, a setter that calls OnPropertyChanged, and optionally a SetProperty helper. That's 45 lines of repetitive garbage per property. Hand-writing it is error-prone. Using CallerMemberName helps slightly but doesn't eliminate the copy-paste.

Solution: mark your class as partial and slap a custom attribute on it. The generator scans for classes with [AutoNotify], reads each field marked [Notify], and generates the full property-with-change-notification for you. No reflection. No runtime overhead. The generated code is as fast as if you wrote it by hand.

The generator pipeline: filter for classes with the attribute, extract fields with a specific marker attribute (or a naming convention like underscore-prefixed), then emit the property wrappers. Keep the generated code in a separate file to avoid confusion. Your source stays clean: just fields and the attribute.

This pattern scales. Extend it to generate ICommand wrappers for methods. Generate logging decorators. Generate JSON serialization contracts. Every time you catch yourself writing the same three-line pattern, ask: "Can I generate this?" If the answer is yes, you just saved future you from a bug.

Remember: Source Generators aren't magic. They're a compiler plugin that writes code you'd write anyway, but faster and with zero typos.

// io.thecodeforge — csharp tutorial

using System.ComponentModel;
using System.Runtime.CompilerServices;

// Source attribute — define in a common project
[AttributeUsage(AttributeTargets.Field)]
public sealed class NotifyAttribute : Attribute { }

// Your ViewModel stays clean: just fields and one attribute
public partial class UserViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    [Notify] private string _userName;
    [Notify] private int _loginCount;
    [Notify] private bool _isActive;

    // PropertyChanged implementation is generated
    // The generator produces:
    // public string UserName { get => _userName; set => SetProperty(ref _userName, value); }
    // public int LoginCount { get => _loginCount; set => SetProperty(ref _loginCount, value); }
    // public bool IsActive { get => _isActive; set => SetProperty(ref _isActive, value); }
    // protected void SetProperty<T>(ref T field, T value, [CallerMemberName] string prop = null)
    // {
    //     if (EqualityComparer<T>.Default.Equals(field, value)) return;
    //     field = value;
    //     PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(prop));
    // }
}

// Consumer code
// var vm = new UserViewModel();
// vm.PropertyChanged += (s, e) => Console.WriteLine($"{e.PropertyName} changed");
// vm.UserName = "Alice";  // Output: "UserName changed"

You Ship Generators Without Tests? Hope You Like Living Dangerously

Source generators produce code at compile time. If your generator has a bug, you don't get a runtime exception. You get a broken .g.cs file that silently corrupts your entire build. No stack trace. No breakpoint. Just confusion.

Testing generators means executing the generator against real compilation objects and asserting the output code compiles and behaves correctly. The standard approach: create a CSharpCompilation with your source files, run the generator via CSharpGeneratorDriver, and inspect the resulting syntax trees. Then compile those trees into an assembly and run unit tests against it.

Your generator should live in a project that references Microsoft.CodeAnalysis.CSharp. Test projects reference both the generator project and the compilation utilities. You don't need a test harness—just a console test fixture that builds, runs, and validates. This catches everything from missing file-scoped namespaces to broken partial method signatures before they reach production.

// io.thecodeforge — csharp tutorial

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;

var source = @"public partial class User { public string Name { get; set; } }";

var compilation = CSharpCompilation.Create("TestAssembly",
    new[] { CSharpSyntaxTree.ParseText(source) },
    new[] { MetadataReference.CreateFromFile(typeof(object).Assembly.Location) });

var driver = CSharpGeneratorDriver.Create(new MyGenerator());
driver.RunGeneratorsAndUpdateCompilation(compilation, out var updatedCompilation, out _);

var generated = updatedCompilation.SyntaxTrees.Last().ToString();
Console.WriteLine(generated.Contains("partial void OnNameChanged") ? "PASS" : "FAIL");

Debug Generators Without Pulling Your Hair Out

Source generators run inside the compiler process. You can't just hit F5 in your generator project. The debugger attaches to the wrong process and you stare at breakpoints that never fire. That's the default experience—and it sucks.

Use a simple trick: add a static bool field to your generator, say Debugger.Launch(). Guard it with an environment variable check so it only triggers when you're explicitly debugging. Then compile your consuming project in Debug mode with that environment variable set. The debugger attaches directly to the compiler process and hits your breakpoints.

Better yet, output generator diagnostics using the context.ReportDiagnostic() method. This surfaces issues as compiler warnings/errors in VS Error List without attaching a debugger. Combined with incremental caching, you get fast iteration: change source, rebuild, and see diagnostics update immediately. No more black-box guesswork.

// io.thecodeforge — csharp tutorial

using System.Diagnostics;

[Generator]
public class MyGenerator : ISourceGenerator
{
    public void Initialize(GeneratorInitializationContext context) { }

    public void Execute(GeneratorExecutionContext context)
    {
        if (Environment.GetEnvironmentVariable("DEBUG_GENERATOR") == "1")
            Debugger.Launch();

        context.ReportNoConfigDiagnostic(
            Diagnostic.Create(
                new DiagnosticDescriptor("GEN001", "Debug", "Generator ran", "Debug", DiagnosticSeverity.Info, true),
                Location.None));
    }
}

Key Takeaways

Source generators change the game by moving runtime work to compile time, but their power comes with strict constraints. You learned that an incremental generator pipeline is essential for performance—relying on caching and equality checks avoids re-running your generator unnecessarily. Real patterns like DTO generation or INotifyPropertyChanged eliminate boilerplate without reflection, yet demand rigorous testing because generated code is invisible until build time. Production pitfalls taught you to handle file paths carefully, avoid global state, and never use \(locals.currentUser. The compiler pipeline revealed that generators execute before emit, meaning they cannot access final assembly metadata. The rule stands: use generators only for repeatable, deterministic code transformations triggered by syntax or attributes. Avoid them for runtime logic, external data, or anything requiring dependency injection. Your generator is a build-time tool, not a runtime library—treat it with the same discipline as hand-written code.

// io.thecodeforge — csharp tutorial
// Key takeaway: always cache and compare inputs
internal class MyIncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitContext context)
    {
        var pipeline = context.SyntaxProvider
            .CreateSyntaxProvider(
                (node, _) => node is ClassDeclarationSyntax,
                (ctx, _) => ctx.Node)
            .Collect()
            .SelectMany((classes, _) => classes.Distinct());

        context.RegisterSourceOutput(pipeline, (spc, classDecl) =>
        {
            var source = $"// Generated from {classDecl.Identifier}\n";
            spc.AddSource(classDecl.Identifier.Text, source);
        });
    }
}

Next Steps

Start by shipping an incremental generator with a real project today—choose a small pain point like automatic constructor generation or partial method stubs. Then, write unit tests using Microsoft.CodeAnalysis.Testing to validate generated output against edge cases: empty inputs, nested types, and multiple files. Next, implement a registration mechanism so your generator can coexist with others without collisions—use unique source name prefixes. For performance, add an IncrementalValueProvider that tracks attribute arguments and syntax tree changes, then profile with the Source Generator Verifier tool. Finally, publish your generator as a NuGet package with a .props file that automatically adds the analyzer reference—this makes adoption seamless. Avoid the trap of over-engineering: start simple, ship early, then expand based on real usage feedback. The best generators feel invisible—they reduce boilerplate so developers focus on business logic, not ceremony.

// io.thecodeforge — csharp tutorial
// Next step: publish a NuGet package with props
// In .nuspec or csproj:
// <files>
//   <file src="bin\Release\netstandard2.0\*.dll" target="analyzers\dotnet\cs" />
// </files>
// Auto-include via buildTransitive\YourGenerator.props:
// <Project>
//   <ItemGroup>
//     <Analyzer Include="$(MSBuildThisFileDirectory)..\analyzers\dotnet\cs\YourGenerator.dll" />
//   </ItemGroup>
// </Project>