Source generators

What it is and why it exists

A source generator runs during C# compilation. It can inspect source, parse options, references, analyzer configuration, and additional files, then use Roslyn APIs to add new SourceText objects. The added source goes through binding, type checking, and code generation like ordinary source.

Generation is additive; it isn’t a source rewriter. A generator can’t delete a statement, replace a method body, or edit a user file. To add members to an existing type, the user declaration and generated declaration usually compose through partial. This boundary keeps generated output inspectable and stops generators from silently rewriting developer input.

Source generation fits repetitive work that can be described statically. System.Text.Json can generate serialization metadata, GeneratedRegexAttribute can generate a regular-expression implementation, and a framework can build registration code from explicit markers. Consumers call ordinary C# members, and the compiler still checks those calls.

A source generator isn’t a macro and has no general ability to transform syntax nodes. It can’t generate code from the current state of an HTTP request or database. When the requirement would replace only a little handwritten code, the cost of another project, packaging, diagnostics, and compatibility tests often exceeds the boilerplate removed.

Consuming a generator and authoring one are different jobs. Consumers mainly care about activation, the generated contract, and publish settings. Authors must also handle Roslyn semantics, incremental invalidation, source escaping, diagnostic locations, and compiler-host compatibility. This topic covers both sides but concentrates on boundaries that generator authors commonly get wrong.

Older codebases still contain ISourceGenerator, while Roslyn documentation directs new implementations toward an incremental generator . Don’t turn that migration advice into a claim that a particular .NET release suddenly removed the old interface. When upgrading an existing generator, pin its generated contract with tests before changing its execution model.

Generated output is an API

Generated members enter the consumer’s compilation view, so their names, accessibility, nullable annotations, and diagnostic ids form a public contract. A template change can be only a patch release for the generator assembly yet stop consumer source from compiling. Version review must inspect more than the generator assembly’s own public types.

Snapshots and compilation tests should state which differences are allowed for the same input across an upgrade. If a member must be renamed or a generation condition changes, provide a migration diagnostic or compatibility period instead of silently removing the member. Formatting-only changes don’t normally break the API, but they still affect snapshots and debugging.

Generator failure is also build behavior. For one invalid target, prefer a diagnostic and continue processing independent targets. Reserve exceptions for violated generator invariants that tests should catch. Swallowing every exception leaves consumers with missing members and discards the actual cause.

Treat a third-party generator upgrade as a source-dependency review. Inspect new diagnostics, generated-member differences, and publish output, especially under trimming or Native AOT settings. Successful package restore doesn’t prove that the generator loads correctly in the targeted compiler host.

How it works

Two compilation views

The compiler builds an initial compilation from user source, runs generators, and adds generated source to an updated compilation. A generator can read the initial compilation but can’t edit its trees. An ordinary source generator also can’t treat another generator’s output as an ordered upstream input because generators have no dependable execution order.

AddSource receives a hint name and source text. The hint should stay stable for the same logical input and be unique within one generator. It is an identity hint for the generated file, not an absolute disk path. Reusing a hint produces a generator error, while timestamps or random values make output change without a business change.

Generated source should declare // <auto-generated/> and an explicit nullable context. When usage is invalid, a generator should call ReportDiagnostic at the relevant user-source location instead of throwing an ordinary exception. An exception usually tells the consumer only that the generator failed; a located diagnostic can explain how to correct the input.

Initialize builds a dataflow graph

IIncrementalGenerator.Initialize describes an immutable dataflow graph; it doesn’t immediately scan the project. The compiler host decides when to execute transformations and caches intermediate results. The compiler also owns generator instance lifetime, so a generator must not keep cross-pass state in instance fields.

Sources appear as IncrementalValueProvider<T> or IncrementalValuesProvider<T>. The first supplies one value per evaluation, such as CompilationProvider; the second supplies zero or more, such as AdditionalTextsProvider. These objects describe computations. They aren’t containers for initialization code to enumerate directly.

Common transformations resemble LINQ, but their purpose is to build an incremental graph. Where removes values, Select projects models, Combine joins two providers, and Collect aggregates a value set into an immutable array. RegisterSourceOutput connects a graph result to source or diagnostic production.

Cache reuse depends on equality between step outputs. Returning a fresh ordinary class, array, or ImmutableArray<T> can keep triggering downstream work even when its contents haven’t changed, because those values may use reference equality. Good models are often records containing strings, Boolean values, and other stable values; collections need an explicit element-wise equality policy.

Syntax filtering and semantic confirmation

A syntax tree retains the structure and textual form of source. It suits a cheap candidate test such as “this is a class declaration with an attribute list.” Syntax text alone can’t reliably identify a type: attributes can use aliases, qualified names, or an omitted Attribute suffix, and an unrelated namespace can define the same short name.

A semantic model binds syntax to types and symbols. When you must recognize a particular attribute, interface, overload, or accessibility level, query semantics during transformation instead of comparing ToString(). After the query, promptly extract the facts you need into a small model rather than carrying an ISymbol or SyntaxNode through the pipeline.

For attribute-driven generators, ForAttributeWithMetadataName combines efficient candidate selection with semantic matching. Its argument is a full metadata name such as Demo.DescribeAttribute; the callback receives the target node, target symbol, and matching attribute data. It avoids the alias and same-name failures common in handwritten suffix tests.

The syntax predicate can run frequently while a developer types. It should check only node shape or the presence of attribute lists, not obtain semantic models, walk the whole compilation, or read files. Pass cancellation tokens to longer reads and transformations so the host can abandon stale work after another edit.

Examples

The first example consumes a platform generator. The second uses GeneratorDriver to inspect a small attribute-driven generator. This environment has no .NET SDK or C# compiler, so each code block carries the repository’s non-execution marker and its output block records only that fact.

Generate an implementation with GeneratedRegex

GeneratedRegexAttribute places the pattern, options, and timeout on a partial method. When the compiler finds the platform generator, it supplies that method’s implementation. The caller depends only on the returned Regex, not an internal generated class name.

The source contains only the method declaration, not a handwritten regex implementation. If the project doesn’t load the required generator, the partial method lacks an implementation and compilation fails. Reflection or configuration doesn’t wait until the first request to reveal the missing generation step. That compile-time failure is part of the generated contract’s value.

Timeout remains part of the call contract. Source generation changes when the implementation is produced; it doesn’t make a problematic pattern safe or replace tests with long inputs. Apply the same distinction to third-party generators: producing code doesn’t prove that the code meets your application boundary.

Test a custom generator with GeneratorDriver

This probe project references Roslyn 5.0.0, matching the C# 14 / .NET 10 target. It puts the generator and driver in one console project solely for a quick verification. A published NuGet package will normally separate the generator assembly from the consumer assembly.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>14.0</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="5.0.0" />
  </ItemGroup>
</Project>

The generator finds public partial classes by the attribute’s full metadata name and immediately projects the symbol into two strings. The output callback no longer holds an INamedTypeSymbol, so the model doesn’t keep an old compilation alive.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System.Text;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.CodeAnalysis.Text;

[Generator]
public sealed class DescribeGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var types = context.SyntaxProvider.ForAttributeWithMetadataName(
            "Demo.DescribeAttribute",
            static (node, _) => node is ClassDeclarationSyntax,
            static (match, _) => new TypeModel(
                match.TargetSymbol.ContainingNamespace.ToDisplayString(),
                match.TargetSymbol.Name));

        context.RegisterSourceOutput(types, static (output, model) =>
        {
            string source = $$"""
                // <auto-generated/>
                #nullable enable
                namespace {{model.Namespace}};
                public partial class {{model.Name}}
                {
                    public static string Describe() => "{{model.Name}}";
                }
                """;

            output.AddSource(
                $"{model.Namespace}.{model.Name}.Describe.g.cs",
                SourceText.From(source, Encoding.UTF8));
        });
    }

    private sealed record TypeModel(string Namespace, string Name);
}

# not executed here: the .NET SDK and C# compilers are unavailable

The driver creates an initial compilation from a string, runs the generator, and queries a type in the updated compilation. Counting generated trees shows that the pipeline emitted a file. Looking up Describe also proves that the generated declaration merged with the user’s partial type.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;
using System.Linq;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;

const string input = """
    namespace Demo;
    [System.AttributeUsage(System.AttributeTargets.Class)]
    public sealed class DescribeAttribute : System.Attribute;
    [Describe]
    public partial class Order { }
    """;

var compilation = CSharpCompilation.Create(
    "Demo",
    [CSharpSyntaxTree.ParseText(input)],
    [MetadataReference.CreateFromFile(typeof(object).Assembly.Location)],
    new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));

GeneratorDriver driver = CSharpGeneratorDriver.Create(
    new DescribeGenerator().AsSourceGenerator());
driver = driver.RunGeneratorsAndUpdateCompilation(
    compilation, out Compilation updated, out _);

var generated = driver.GetRunResult().GeneratedTrees;
var order = updated.GetTypeByMetadataName("Demo.Order")!;
Console.WriteLine($"generated: {generated.Length}");
Console.WriteLine($"Describe members: {order.GetMembers("Describe").Length}");
Console.WriteLine($"errors: {updated.GetDiagnostics().Count(
    diagnostic => diagnostic.Severity == DiagnosticSeverity.Error)}");

# not executed here: the .NET SDK and C# compilers are unavailable

A real test should assert generated text, hint names, and diagnostics, not only a count. Treat error diagnostics from the updated compilation as a failure as well; that catches a generator that emitted a file which doesn’t bind. For negative input, verify the diagnostic id, severity, and Location point to source the consumer can fix.

This small generator deliberately supports only top-level, non-generic, public classes. If the product contract permits nested types, records, generics, or the global namespace, expand the model and emitter and add an input for each shape. A simple sample isn’t evidence of a broader contract.

Pitfalls

Matching attributes by syntax text

Fix: use ForAttributeWithMetadataName with the full metadata name for semantic matching. Test a short name, suffixed name, alias, global:: qualification, and an unrelated attribute with the same short name.

Keeping Roslyn objects in cached models

Fix: use them in the step that needs semantics, then project into value-equatable records. Give collections element-wise equality; merely putting an array in a record doesn’t make its contents value-equatable.

Calling Collect too early

Fix: keep a values provider itemized and register output directly for each model. Aggregate only when sorting, duplicate detection, or one global registry truly needs the complete set, and define a stable order afterward.

Emitting an incomplete type declaration

Fix: write a supported-input matrix first, then extract type kind, container chain, and required modifiers from symbols. Report a located diagnostic for unsupported shapes instead of emitting source that causes cascading compiler errors.

Failing to escape identifiers and literals

Fix: treat identifier, type-display, and string-literal contexts separately and use the corresponding Roslyn escaping or formatting support. Test generated text with quotes, newlines, keywords, generics, and nullable types, then compile that text.

Letting output drift with the environment

Fix: compute output only from declared inputs, sort any collection without a contractual order, and use stable unique hint names. If build information is required, model it as explicit configuration and decide whether it deserves to invalidate the cache.

Depending on another generator’s ordinary output

Fix: make both generators consume user declarations, additional files, or an ordinary runtime contract instead of each other’s output. If two phases require ordering, keep the protocol in one generator and use only phase APIs explicitly supported by the targeted Roslyn version.

Further reading

• Roslyn source generators design
• Roslyn incremental generators design
• Incremental generators cookbook
• IIncrementalGenerator API
• ForAttributeWithMetadataName API
• System.Text.Json source generation