源生成器

是什么，为什么存在

源生成器在 C# 编译过程中运行。它可以查看待编译源码、解析选项、引用、分析器配置与额外文件，并通过 Roslyn API 向编译加入新的 SourceText。加入的源码随后像普通源码一样接受绑定、类型检查和代码生成。

它是加法机制，不是源码重写器。生成器不能删除语句、替换方法体或改变用户文件；需要给已有类型增加成员时，用户声明和生成声明通常通过 partial 组成同一个类型。这条边界让生成结果可以独立查看，也避免生成器暗中改写开发者输入。

源生成适合把可静态描述的重复工作搬到编译期。System.Text.Json 可以生成序列化元数据，GeneratedRegexAttribute 可以生成正则表达式实现，框架也可以根据显式标记生成注册代码。消费者得到普通 C# 成员，编译器仍会检查这些成员的调用。

源生成器不是宏，也没有权限修改任意语法节点。它不能根据一次 HTTP 请求或数据库中的即时状态生成代码。若需求只涉及少量手写代码，生成器项目、打包、诊断和兼容性测试的成本通常高于它消除的样板代码。

使用现成生成器与编写生成器是两种不同工作。使用者主要关心启用方式、生成契约和发布配置；作者还必须处理 Roslyn 语义、增量失效、源码转义、诊断位置与编译器宿主兼容性。这个主题覆盖两边，但重点放在作者容易写错的边界。

旧的 ISourceGenerator 仍能在代码库中见到，Roslyn 文档建议新实现采用 增量生成器（incremental generator） 。不要把这个迁移建议误写成某个 .NET 版本突然移除了旧接口；升级现有生成器时，应先用测试固定生成契约，再改变执行模型。

生成结果也是 API

生成成员会进入消费者的编译视图，因此名称、可访问性、可空注解和诊断 id 都属于公开契约。修改模板可能让生成器包只增加一个补丁版本，却使使用者源码无法编译；版本评审不能只看生成器自身程序集的公开类型。

同一个输入升级前后应产生怎样的差异，需要用快照与编译测试表达。若必须重命名成员或改变生成条件，应提供可迁移的诊断或兼容期，而不是静默让成员消失。生成代码的格式变化通常不破坏 API，但仍会影响快照和调试。

生成器失败也属于构建行为。对单个无效目标，最好报告诊断并继续处理其他独立目标；生成器自身违反不变量时才应让测试捕获异常。把所有异常吞掉会留下缺失成员，却丢失真正原因。

使用第三方生成器时，要把升级结果当作源码依赖审查。查看新增诊断、生成成员差异和发布产物，尤其要测试裁剪或 Native AOT 配置。包能恢复并不等于它在目标编译器宿主中正确加载。

工作原理

两次编译视图

编译器先根据用户源码建立初始编译，运行生成器，再把生成源码加入更新后的编译。生成器能读取初始编译，却不能编辑其中的树。普通源生成器也不能把另一个生成器的输出当成有序的上游输入，因为生成器之间没有可依赖的执行顺序。

AddSource 接收提示名称与源码文本。提示名称应对同一逻辑输入保持稳定，并且在一个生成器内唯一；它是生成文件的身份线索，不是磁盘绝对路径。相同提示名称被重复添加会产生生成器错误，而时间戳或随机数又会让没有业务变化的输出不断改变。

输出源码应包含 // <auto-generated/> 与明确的可空上下文。生成器遇到用法错误时，应通过 ReportDiagnostic 指向用户源码中的相关位置，而不是抛出普通异常。异常通常只告诉使用者「生成器失败」，有位置的诊断才能说明怎样修正输入。

Initialize 建立数据流

IIncrementalGenerator.Initialize 描述一张不可变的数据流图，而不是立即扫描项目。编译器宿主决定何时执行各个转换，并缓存中间结果。生成器实例的生命周期也由编译器控制，因此不能把跨轮次状态保存在实例字段中。

数据源以 IncrementalValueProvider<T> 或 IncrementalValuesProvider<T> 表示。前者每次提供一个值，例如 CompilationProvider；后者提供零到多个值，例如 AdditionalTextsProvider。这些对象代表计算，不是让初始化代码直接读取的容器。

常见转换与 LINQ 外形相似，但语义是构建增量图。Where 筛掉值，Select 投影模型，Combine 合并两个提供者，Collect 把一组值聚合成一个不可变数组。RegisterSourceOutput 把图的某个结果连接到源码或诊断输出。

缓存命中取决于步骤输出的相等性。每次都返回新的普通类、数组或 ImmutableArray<T>，即使内容相同，也可能因为引用相等而继续触发下游。适合的模型通常是只含字符串、布尔值和其他稳定值的 record，集合则需要明确的逐项相等策略。

语法筛选与语义确认

语法树（syntax tree） 保留源码的结构与文本形态。它适合做便宜的候选筛选，例如「这是带特性列表的类声明」。仅凭语法文本无法可靠判断类型身份：特性可以使用别名、限定名或省略 Attribute 后缀，同名类型也可能来自别的命名空间。

语义模型（semantic model） 把语法绑定到类型与符号。需要识别某个特性、接口、重载或可访问性时，应在转换阶段查询语义，而不是比较 ToString()。完成查询后，应尽快把所需事实提取成小模型，不要让 ISymbol 或 SyntaxNode 沿管道长期传播。

针对特性驱动的生成器，ForAttributeWithMetadataName 同时提供高效候选筛选与语义匹配。参数使用完整元数据名，例如 Demo.DescribeAttribute；回调得到目标节点、目标符号和匹配的特性数据。它能避开手写字符串后缀判断常见的别名与同名类型错误。

语法谓词可能在编辑器输入期间频繁执行。这里应只检查节点种类或是否存在特性列表，不应获取语义模型、遍历整个编译或读文件。取消令牌要传给可能较长的读取与转换，避免用户继续编辑后，宿主仍为过期快照做工作。

示例

下面两个示例先展示如何消费平台自带生成器，再用 GeneratorDriver 检查一个最小的特性驱动生成器。当前环境没有 .NET SDK 或 C# 编译器，因此代码块按仓库规则标明未执行，输出块也只记录这一事实。

使用 GeneratedRegex 生成实现

GeneratedRegexAttribute 把模式、选项与超时放在一个 partial 方法上。编译器找到平台提供的生成器后，为该方法补上实现；调用方只依赖返回的 Regex，不需要知道生成类的内部名称。

源码里只有方法声明，没有手写正则表达式实现。若项目没有加载相应生成器，partial 方法会缺少实现并在编译期失败，而不是到第一次请求时才发现反射或配置错误。这正是生成契约的价值：缺失的生成步骤会暴露为构建问题。

超时仍属于调用契约。源生成只改变实现产生的时机，不会让有问题的模式自动安全，也不会替代针对长输入的测试。审查第三方生成器时，同样要区分「生成了代码」与「生成代码满足业务边界」。

用 GeneratorDriver 测试自定义生成器

这个探针项目引用 Roslyn 5.0.0，与 C# 14／.NET 10 目标一致。它把生成器和测试驱动放在一个控制台项目中，仅用于快速验证；发布 NuGet 包时，生成器程序集与使用者程序集通常需要分开。

<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>

生成器按特性的完整元数据名查找公开的部分类，并立即把符号投影成两个字符串。输出回调不再持有 INamedTypeSymbol，因此旧编译不会因为模型对象而长期存活。

// # 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

测试驱动从字符串建立初始编译，运行生成器，再查询更新后编译中的类型。断言生成树数量只能检查管道是否产出文件；查询 Describe 成员还能证明生成声明确实与用户的 partial 类型合并。

// # 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

真正的测试应断言生成文本、提示名称与诊断，而不只看数量。再把更新后编译的错误诊断视为失败，才能抓到生成了文件但文件无法绑定的情况。对负面输入，还要检查诊断 id、严重级别和 Location 是否落在用户能修正的源码上。

这个最小生成器故意只处理顶层、非泛型、公开类。若产品契约允许嵌套类型、记录、泛型或全局命名空间，就必须扩展模型与发射器，并为每种形态增加测试。生成器不能靠「样例正好简单」来暗示更宽的支持范围。

陷阱

用语法文本识别特性

**修正：**使用 ForAttributeWithMetadataName 和完整元数据名进行语义匹配。测试短名、带后缀名称、别名、global:: 限定名和同名无关特性。

把 Roslyn 对象留在缓存模型中

**修正：**在需要语义的步骤读取它们，随后投影成值相等的记录。集合要有逐项相等策略；仅把数组放进 record 并不会自动得到内容相等。

过早调用 Collect

**修正：**尽量让多值提供者保持逐项流动，并为每个模型直接注册输出。只有排序、查重或生成一个全局注册表确实需要完整集合时才聚合，而且要固定排序规则。

发射不完整的类型声明

**修正：**先写清支持矩阵，再从符号提取类型种类、容器链和所需修饰符。对不支持的形态报告带位置的诊断，不要输出一份注定产生级联编译错误的源码。

不转义标识符与字面量

**修正：**区分标识符、类型显示与字符串字面量三种上下文，分别使用 Roslyn 的转义或格式化能力。用包含引号、换行、关键字、泛型和可空类型的输入测试生成文本，并编译该文本。

让输出随环境漂移

**修正：**只从声明的输入计算输出，排序任何没有契约顺序的集合，并使用稳定且唯一的提示名称。确需构建信息时，把它作为明确配置输入，并决定它是否值得使缓存失效。

依赖另一个生成器的普通输出

**修正：**让生成器共享用户声明、额外文件或一个普通运行时契约，而不是相互读取输出。若两个阶段必须有顺序，把协议收进一个生成器，并使用目标 Roslyn 版本明确支持的阶段 API。

延伸阅读

• Roslyn 源生成器设计
• Roslyn 增量生成器设计
• 增量生成器 Cookbook
• IIncrementalGenerator API
• ForAttributeWithMetadataName API
• System.Text.Json 源生成