Skip to content
Tutorials Center
My learning

Topics

Lesson 161 of 182 ยท Advanced C#

Source Generators and Roslyn

Learn how C# source generators work: partial classes, GeneratedRegex, LoggerMessage, System.Text.Json, incremental generators, Roslyn syntax trees and when to write your own.

Every C# program contains boilerplate that nobody enjoys writing: ToString methods that list every property, mapping code that copies one object into another, JSON converters, logging wrappers, regular expression matchers. You can write this code by hand (tedious and easy to get out of date), or you can use reflection to do it at run time (convenient, but slower, and it breaks under trimming and Native AOT).

A source generator is the third option. It is a small program that runs inside the compiler. It looks at your code, and while the compile is still happening it writes extra C# files that are compiled together with yours. The result is ordinary, fast, fully typed code that exists before the program ever starts, with no reflection at run time.

The big picture

The C# compiler is called Roslyn. It is not a black box: it is a library that turns source text into a syntax tree (the grammar of your code), then into a semantic model (what each name means: which type, which method, which overload), and finally into IL. Roslyn exposes all of this through public APIs in the Microsoft.CodeAnalysis packages. Two kinds of tools plug into that pipeline:

  • Analyzers inspect your code and report warnings and errors (and offer code fixes). They are the subject of analyzers and code style.
  • Source generators inspect your code and add new source files to the compilation.

One rule defines what a generator can do: it can only add code, never change or remove yours. If it needs to put a method into your class, that class must already be declared partial, so the generator can supply another piece of the same class in a different file. That is why you see partial everywhere in modern C#.

TEXT
your .cs files โ”€โ”€โ–บ Roslyn parses them โ”€โ”€โ–บ generator reads the syntax/semantic model
                                              โ”‚
                                              โ–ผ
                              generator emits Extra.g.cs (text)
                                              โ”‚
your .cs files + Extra.g.cs โ”€โ”€โ–บ compiled together โ”€โ”€โ–บ one assembly (IL)

Source generators arrived with C# 9 and .NET 5. The first API (ISourceGenerator) was simple but slow in an editor, because it re-ran on every keystroke. The current design, incremental generators (IIncrementalGenerator, since .NET 6 and Visual Studio 2022), caches intermediate results so the IDE stays responsive. New generators should always be incremental.

Generators you already use

You do not have to write a generator to benefit from them. The .NET libraries ship several, each one triggered by an attribute on a partial member or class:

Attribute Since What it generates
[GeneratedRegex] .NET 7 A hand-optimized matcher class for a regular expression with a constant pattern
[LoggerMessage] .NET 6 A high-performance logging method that skips string formatting when the level is off
[JsonSerializable] .NET 6 Serialization metadata for System.Text.Json, so no reflection is needed
[LibraryImport] .NET 7 The marshalling stub for a native call (see interop)
[GeneratedComInterface] .NET 8 COM interop wrappers

Here is what they look like in a normal project. These snippets need the real SDK, so they are read-only:

C#
// Read-only: works in a project built with the .NET SDK.
using System.Text.RegularExpressions;

public static partial class Patterns
{
    // The compiler generates the body of Iso() at build time.
    [GeneratedRegex(@"(?<y>\d{4})-(?<m>\d\d)-(?<d>\d\d)")]
    public static partial Regex Iso();
}

public static partial class AppLog
{
    // Generates a logging method with typed parameters and no boxing.
    [LoggerMessage(EventId = 1, Level = LogLevel.Information,
                   Message = "User {Name} started {Count} jobs")]
    public static partial void Started(ILogger logger, string name, int count);
}

The method has no body. A partial method declaration promises that another part of the program will supply the implementation, and the generator is that other part. The page on regular expressions covers why GeneratedRegex matters: the regex is compiled to C# at build time, so there is no start-up cost for parsing the pattern and the JIT can optimize the code.

What happens when no generator runs

Our in-browser editor compiles a single file with the compiler alone and has no generators wired in. That makes it a good place to see exactly what a generator is replacing. Run this and read the error.

C# A partial method nobody implements (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The compiler reports error CS8795: Partial method 'Patterns.Iso()' must have an implementation part because it has accessibility modifiers. In a real project the generator would have supplied that implementation part, and the error would never appear. The same declaration with no generator is simply incomplete code.

What a generator produces: partial classes by hand

To understand generated code, write it yourself once. Suppose you want every "described" class to have a Describe() method that lists its properties. You mark the class with an attribute and make it partial; the generator's job would be to write the second half. Here is the second half written by hand, so it runs.

C# The two halves of a partial class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Notice the benefits. Describe() is plain compiled code: no reflection, no allocation of PropertyInfo objects, and the trimmer sees exactly which properties are used. Notice the cost too: for ten classes you would write ten of these by hand. A generator writes them all from a single description of the pattern.

Partial methods with a body supplied elsewhere (the public partial string Describe(); form above) need C# 9 or later. Before that, partial methods had to be void and private, and the call simply disappeared if there was no implementation.

A generator in miniature

A real generator walks Roslyn's syntax tree. We do not have the Roslyn libraries here, but we can imitate the shape of a generator: find the types that carry the marker attribute, look at their properties, and produce C# source text. This one uses reflection over the running program, which a real generator never does (it has no running program; it works on source), but the output step, building text with a StringBuilder, is exactly what a real generator does.

C# A toy generator that writes C# text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The printed text is exactly the code we wrote by hand a moment ago. That is a source generator at its simplest: inspect, then print code. A real generator hands that text to Roslyn with context.AddSource("Book.g.cs", text), and the compiler treats it as another file in your project.

Writing an incremental generator (read-only)

Building a generator needs a separate project, because the compiler must load it before it compiles yours. It targets netstandard2.0 (the compiler hosts load generators in many runtimes) and references the Microsoft.CodeAnalysis.CSharp NuGet package. Both are things our editor cannot do, so this part is for your own machine.

XML
<!-- DescribeGenerator.csproj  (read-only: needs the dotnet SDK and NuGet) -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <IsRoslynComponent>true</IsRoslynComponent>
    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.*" PrivateAssets="all" />
  </ItemGroup>
</Project>
C#
// Read-only: DescribeGenerator.cs
using System.Linq;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp.Syntax;

[Generator]
public sealed class DescribeGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // Step 1: find classes with [AutoDescribe]. This is the cheap, cached part.
        var classes = context.SyntaxProvider.ForAttributeWithMetadataName(
            "AutoDescribeAttribute",
            predicate: static (node, _) => node is ClassDeclarationSyntax,
            transform: static (ctx, _) =>
            {
                var symbol = (INamedTypeSymbol)ctx.TargetSymbol;
                var props = symbol.GetMembers().OfType<IPropertySymbol>()
                                  .Select(p => p.Name).ToArray();
                return new Model(symbol.Name, new EquatableArray(props));
            });

        // Step 2: turn each model into a source file.
        context.RegisterSourceOutput(classes, static (spc, model) =>
        {
            var body = string.Join(", ", model.Props.Items.Select(p => $"{p} = {{{p}}}"));
            spc.AddSource($"{model.Name}.g.cs", $$"""
                public partial class {{model.Name}}
                {
                    public partial string Describe() => $"{{model.Name}}: {{body}}";
                }
                """);
        });
    }
}
// Model and EquatableArray are small records you write so the pipeline can tell
// when the input has really changed (see the next section).

You use the generator from an application project with a project reference that marks it as an analyzer, so it runs but is not shipped with your app:

XML
<ProjectReference Include="..\DescribeGenerator\DescribeGenerator.csproj"
                  OutputItemType="Analyzer" ReferenceOutputAssembly="false" />

Why the pipeline looks the way it does

An editor re-runs generators after nearly every keystroke, so a slow generator makes the whole IDE feel sluggish. The incremental design is built around caching:

  • Each step of the pipeline (ForAttributeWithMetadataName, Select, Combine) caches its output. If a step's input is equal to last time, everything after it is skipped.
  • Equality is the key. The model you pass between steps must be a type with value equality (a record or record struct), and it must contain only simple data such as strings and arrays-wrapped-in-equatable types. If you put an ISymbol or a SyntaxNode into the model, equality is by reference, the cache never hits, and you also keep whole compilations alive in memory.
  • ForAttributeWithMetadataName is far cheaper than scanning every syntax node, because Roslyn indexes attributes for you. Prefer it whenever your generator is triggered by an attribute.

Roslyn syntax trees and semantic models

Underneath, every generator works with two views of the code. The syntax tree is the pure structure: a ClassDeclarationSyntax contains a list of PropertyDeclarationSyntax, each with a type token and an identifier token. It knows nothing about meaning. The semantic model answers questions like "what type is this identifier?" or "which overload does this call bind to?", and exposes symbols (INamedTypeSymbol, IMethodSymbol) that represent compiled meaning, including types from other assemblies.

You can explore both with the Roslyn packages in a console project:

C#
// Read-only: needs the Microsoft.CodeAnalysis.CSharp NuGet package.
var tree = CSharpSyntaxTree.ParseText("class C { int X { get; set; } }");
var root = tree.GetCompilationUnitRoot();
foreach (var prop in root.DescendantNodes().OfType<PropertyDeclarationSyntax>())
{
    Console.WriteLine(prop.Identifier.Text);   // X
}

Why not just search the text with a regular expression? A short experiment shows why a tree is worth the trouble.

C# Why generators parse trees, not text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Comments, strings, nested types, attributes spread over several lines, partial declarations in different files, using aliases: text matching breaks on all of them, while the syntax tree has already sorted them out.

Practical advice

  • Reach for a built-in generator first. GeneratedRegex, LoggerMessage, System.Text.Json source generation and LibraryImport are maintained by the .NET team and need only an attribute.
  • Write your own when you have a repeated pattern across many types, you need Native AOT compatibility, or reflection shows up as a cost in your profile. Typical examples: mappers, enum string tables, strongly typed IDs, dependency-injection registration lists.
  • Do not write one when a normal generic method, an extension method, or a small helper does the job. A generator adds a separate project, build complexity and a debugging story.
  • Seeing the output. Set <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> in the consuming project and the generated .g.cs files are written under obj/. In Visual Studio and Rider they also appear under Dependencies, then Analyzers.
  • Report problems as diagnostics, not exceptions. A crashing generator turns into a confusing compiler warning for everyone who uses it.
  • Generators cannot see each other's output. Do not design one that depends on code another generator emits.

When you are unsure whether something is a good generator candidate, ask: "Would I otherwise write this method by copy-and-paste for every type?" If yes, and the shape is mechanical, it is.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What can a C# source generator do to your existing code?

    Generators are additive. They can add files, which is why they depend on partial classes and partial methods to extend your own types.
  2. 2. Why does a class that uses a generator usually need the partial keyword?

    A partial class may be declared in several files. The generator supplies one of them, since it cannot edit yours.
  3. 3. What error do you get when you declare 'public static partial Regex Iso();' but no generator provides the body?

    CS8795 says the partial method must have an implementation part because it has accessibility modifiers.
  4. 4. Why should the model passed between incremental-generator steps be a record with plain data rather than a SyntaxNode or ISymbol?

    Caching depends on equality. Symbols and syntax nodes compare by reference, so the cache would never hit, and they hold large compiler objects in memory.
  5. 5. Which of these is a built-in source generator trigger in .NET?

    [LoggerMessage] (.NET 6) generates logging methods. [Serializable], [Obsolete] and [Flags] are ordinary attributes read at run time or by the compiler itself.

Summary

  • A source generator runs inside the compiler (Roslyn) and adds C# files; it never edits your code.
  • Generated code is normal compiled code: no run-time reflection, friendly to trimming and Native AOT.
  • Use partial classes and partial methods as the hook where generated code attaches.
  • Built-in generators: GeneratedRegex, LoggerMessage, JsonSerializable, LibraryImport.
  • Write new generators as IIncrementalGenerator, use ForAttributeWithMetadataName, and keep pipeline models as value-equatable records.
  • Generators work on syntax trees and semantic models, not on text, and need a separate netstandard2.0 project with the Roslyn NuGet package.

Next: Native AOT, Trimming and Startup