Developing Source Generators in C#

Source generators are a powerful feature in C# that enable developers to dynamically generate C# code during compile time. Introduced with C# 9 and .NET 5, they have become a vital tool for reducing boilerplate, automating repetitive tasks, and improving performance by shifting code generation from runtime to compile-time.

What Are Source Generators?

A source generator is a type of Roslyn analyzer that inspects your code during compilation and produces additional C# source files. These files are automatically included in your project, allowing you to extend functionality without manually writing repetitive code. Unlike traditional code generation techniques that require multiple build steps, source generators run as part of the compilation, ensuring that the generated code is immediately available.

Why Use Source Generators? Source generators are most effective when:

• Reducing Boilerplate: For example, creating Equals, GetHashCode, and ToString methods based on class properties, or generating DTOs (Data Transfer Objects).
• Compile-Time Code Analysis: Analyzing code for errors or applying best practices during compilation, such as validating required attributes.
• Performance Optimization: Replacing runtime reflection-based code with generated code for scenarios like serialization or deserialization.
• Interfacing with External APIs: Creating strongly-typed wrappers or API clients that automatically reflect changes in the service’s specifications.

Setting Up a Source Generator Project

Prerequisites

Before building a source generator, ensure you have a good understanding of C# and are familiar with .NET Standard libraries, as generators often need to target .NET Standard 2.0 to maintain compatibility with various projects. The latest versions of Visual Studio, specifically Visual Studio 2022, and the .NET Compiler Platform SDK are recommended for the best development experience.

Project Setup

Create a .NET Standard Class Library:

dotnet new classlib -n MySourceGenerator -f netstandard2.0

Add Roslyn NuGet Packages: Add references to the Roslyn SDK for accessing syntax and semantic APIs:

dotnet add package Microsoft.CodeAnalysis.CSharp --version 4.0.0

Implement the IIncrementalGenerator Interface: With .NET 6 and later, it is recommended to implement IIncrementalGenerator instead of ISourceGenerator for better performance. Incremental generators improve efficiency by only running when necessary code changes are detected.

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

[Generator]
public class MyGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        context.RegisterPostInitializationOutput(ctx =>
        {
            ctx.AddSource("GeneratedAttribute", SourceText.From(@"
                [System.AttributeUsage(System.AttributeTargets.Class)]
                public class AutoGeneratedAttribute : System.Attribute
                {
                }
            ", Encoding.UTF8));
        });

        var classDeclarations = context.SyntaxProvider
            .CreateSyntaxProvider(
                predicate: (syntaxNode, _) => syntaxNode is ClassDeclarationSyntax,
                transform: (ctx, _) => (ClassDeclarationSyntax)ctx.Node)
            .Where(node => node.AttributeLists.Any(a => 
                a.Attributes.Any(attr => attr.Name.ToString() == "AutoGenerated")))
            .Collect();

        context.RegisterSourceOutput(classDeclarations, GenerateClassCode);
    }

    private static void GenerateClassCode(SourceProductionContext context, ImmutableArray<ClassDeclarationSyntax> classes)
    {
        foreach (var classDeclaration in classes)
        {
            var className = classDeclaration.Identifier.Text;
            var source = $@"
            namespace GeneratedNamespace
            {{
                public partial class {className}
                {{
                    public string GetClassName() => ""{className}"";
                }}
            }}";
            context.AddSource($"{className}_Generated.cs", SourceText.From(source, Encoding.UTF8));
        }
    }
}

This example uses IIncrementalGenerator and includes a post-initialization step to add an AutoGenerated attribute that marks classes for which the source generator should run.

Deep Dive: Working with the Syntax and Semantic APIs

Understanding and utilizing both the syntax and semantic APIs are essential for effective source generator development.

Syntax API

The Syntax API lets you analyze the structure of the code, such as classes, properties, and methods. It is ideal for pattern-matching scenarios where you need to find specific constructs, like classes marked with an attribute.

Example:

• Using ClassDeclarationSyntax to analyze class structures:

var classes = context.SyntaxProvider
    .CreateSyntaxProvider(
        predicate: (syntaxNode, _) => syntaxNode is ClassDeclarationSyntax,
        transform: (ctx, _) => (ClassDeclarationSyntax)ctx.Node);

Semantic API

The Semantic API goes beyond syntax to provide richer information about types and symbols, similar to using reflection at runtime but during compilation. This is crucial for scenarios where you need to ensure that specific types or attributes come from a particular namespace or assembly.

Example:

• Validating an attribute’s namespace using SemanticModel:

var semanticModel = context.SemanticModel;
var classSymbol = semanticModel.GetDeclaredSymbol(classDeclaration);
var attributeSymbol = semanticModel.Compilation.GetTypeByMetadataName("MyProject.AutoGeneratedAttribute");

if (classSymbol.GetAttributes().Any(a => 
    SymbolEqualityComparer.Default.Equals(a.AttributeClass, attributeSymbol)))
{
    // Proceed with code generation
}

This method checks if a class is decorated with a specific attribute, ensuring that it’s the right one by validating its namespace. This is particularly useful in preventing unintended generation from similarly named attributes in different namespaces.

Advanced Scenarios and Performance Optimization

Managing Partial Classes and Supporting File-Scoped Namespaces

With C# 10, file-scoped namespaces simplify code by removing the need for curly braces around namespace declarations. To support both block-scoped and file-scoped namespaces, adjust the SyntaxNode traversal accordingly:

var namespaceName = classDeclaration.FirstAncestorOrSelf<NamespaceDeclarationSyntax>()?.Name.ToString() ??
                    classDeclaration.FirstAncestorOrSelf<FileScopedNamespaceDeclarationSyntax>()?.Name.ToString();

This approach ensures that your generator remains compatible with newer C# language features, helping you support a broader range of projects without breaking changes.

Using the Collect Method

The Collect method can be applied in the generator pipeline when you need to aggregate results across multiple syntax nodes:

var collectedClasses = classes.Collect();

This results in an ImmutableArray, which allows you to iterate through all relevant classes in a single step, potentially improving efficiency for batch operations like generating registries or dependency injection code.

Implementing Equality Checks for Cache Efficiency

Source generators use internal caching to determine if code generation is necessary upon changes. Implementing equality checks on your data models ensures that unchanged input doesn’t trigger unnecessary code generation:

public class ClassToGenerate : IEquatable<ClassToGenerate>
{
    public string NamespaceName { get; }
    public string ClassName { get; }
    public IEnumerable<string> PropertyNames { get; }

    public bool Equals(ClassToGenerate other) =>
        other != null &&
        NamespaceName == other.NamespaceName &&
        ClassName == other.ClassName &&
        PropertyNames.SequenceEqual(other.PropertyNames);

    public override int GetHashCode() => HashCode.Combine(NamespaceName, ClassName);
}

This custom equality check ensures that changes to non-relevant parts of the code (e.g., adding a comment) don’t cause the source generator to regenerate output, significantly improving performance, especially in large projects.

Real-World Scenario: Automating Serialization

Consider a scenario where you frequently need to serialize classes into JSON strings. Instead of relying on runtime reflection-based libraries like Newtonsoft.Json, you can use a source generator to create compile-time serialization methods:

public void Execute(GeneratorExecutionContext context)
{
    var source = @"
    public partial class Customer
    {
        public string SerializeToJson() => $""{{ \"Id\": \"{Id}\", \"Name\": \"{Name}\" }}"";
    }";
    context.AddSource("Customer_Serialization.cs", SourceText.From(source, Encoding.UTF8));
}

This approach removes the need for runtime reflection, yielding better performance for high-throughput services that serialize large numbers of objects.

Summary

• Source generators are a versatile tool that automates code generation at compile-time, leading to more maintainable and efficient applications.
• Incremental generators provide better performance in large solutions by only triggering code generation when necessary.
• Leveraging syntax and semantic models allows fine-grained control over what code gets generated and when, offering a robust alternative to traditional code generation techniques.
• Real-world applications include automating ToString() methods, serialization, and API client generation, demonstrating how source generators can transform repetitive development tasks into streamlined, automated processes.