第 3 章：理解三工程结构

本章目标

• 理解为什么案例拆成三个工程
• 知道生成器工程、示例工程、测试工程分别负责什么
• 理解 Analyzer 引用为什么关键

先看现象

sample/01-tostring-generator 下有三个主要工程：

• ToStringGenerator
• ToStringGenerator.Sample
• ToStringGenerator.Tests

很多新手第一次看到会问：为什么不做成一个工程？

因为三者的职责完全不同：

• 一个负责生成代码
• 一个负责使用生成器
• 一个负责验证生成结果

如果你还没建立目录感，先看 源码导读 再回来，会更容易。

再看代码

1. 生成器工程

• sample/01-tostring-generator/ToStringGenerator

这里放的是真正的生成器实现，也就是你之后要重点看的 ToStringGenerator.cs。

2. 示例工程

• sample/01-tostring-generator/ToStringGenerator.Sample

这个工程模拟真实业务项目怎么使用生成器。它的任务不是实现生成器，而是“像一个普通使用者那样去引用并触发它”。

3. 测试工程

• sample/01-tostring-generator/ToStringGenerator.Tests

这个工程负责自动验证：输入一段代码后，生成器是否产出了符合预期的结果。

示例工程为什么是 Analyzer 引用

打开：

• sample/01-tostring-generator/ToStringGenerator.Sample/ToStringGenerator.Sample.csproj

你会看到：

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

这三行很关键：

• ProjectReference
  • 表示引用另一个项目
• OutputItemType="Analyzer"
  • 表示把这个项目当成分析器/生成器接入编译
• ReferenceOutputAssembly="false"
  • 表示不要把它当成普通运行时依赖输出给业务工程

如何验证

按下面顺序做：

1. 先打开 sample/01-tostring-generator
2. 分别看看三个工程目录里主要有哪些文件
3. 打开 ToStringGenerator.Sample.csproj
4. 找到 OutputItemType="Analyzer"
5. 再打开 sample/01-tostring-generator/ToStringGenerator.Tests/TestHelpers.cs，确认测试工程确实在手动跑生成器

常见误解

• 误解 1：生成器工程只是一个普通类库
  • 不是，它是会参与编译流程的特殊组件
• 误解 2：测试工程只是可选的
  • 对源生成器来说，测试非常重要，因为光靠肉眼看生成结果不可靠
• 误解 3：示例工程引用生成器和普通项目引用没区别
  • 区别很大，Analyzer 引用是让它在编译时生效的关键

本章新名词

• ProjectReference
• OutputItemType="Analyzer"
• ReferenceOutputAssembly="false"

本章小结

生成器工程是生产者，示例工程是使用者，测试工程是质检者。只有把这三个角色分清楚，后面你才不会一直混淆“谁在生成，谁在使用，谁在验证”。

下一章开始，我们终于要进入生成器本体，看一个最小的增量生成器骨架长什么样。

上一章 | 返回主教程目录 | 下一章：最小源生成器骨架