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.