术语分册 6：驱动与跟踪

这一册负责解释“生成器到底生成了什么”“哪一步重新跑了”“增量组合对象怎么理解”。

GeneratorDriver

• 一句话说明：运行生成器并读取运行结果的驱动对象
• 什么时候会用到：测试里手工驱动生成器，或深入查看运行结果时
• 对应教程：第 12 章

关键成员：

成员	能拿到什么
RunGeneratorsAndUpdateCompilation(...)	运行生成器并更新编译
RunGenerators(...)	仅运行生成器
GetRunResult()	查看本次运行的详细报告

GetRunResult()

• 一句话说明：获取一次驱动运行的总结果
• 什么时候会用到：你不只想看最终语法树，还想知道归因和分生成器结果时

GeneratorDriverRunResult

• 一句话说明：一次驱动运行的总报告
• 什么时候会用到：你要看这次总共生成了哪些树、有哪些诊断、每个生成器各自产出了什么

关键成员：

成员	能拿到什么
GeneratedTrees	本次总共生成的语法树
Diagnostics	本次总诊断
Results	每个生成器各自的结果

GeneratorRunResult

• 一句话说明：单个生成器的运行结果
• 什么时候会用到：你要只分析某个生成器本身

关键成员：

成员	能拿到什么
GeneratedSources	这个生成器生成的源码列表
Diagnostics	这个生成器自己的诊断
Exception	这个生成器是否抛异常
TrackedSteps	普通增量步骤的跟踪信息
TrackedOutputSteps	输出步骤的跟踪信息

GeneratedSourceResult

• 一句话说明：单条生成源码的结果对象
• 什么时候会用到：你想知道某条源码的 HintName、文本和语法树时

关键成员：

成员	能拿到什么
HintName	提示名
SourceText	源码文本
SyntaxTree	对应语法树

IncrementalValuesProvider<T>

• 一句话说明：表示“多项结果流”的增量 provider
• 什么时候会用到：你的筛选会产生多个目标时

Collect(...)

• 一句话说明：把多项结果收集成集合
• 什么时候会用到：你后续需要一次性看所有输入时

Combine(...)

• 一句话说明：把两个输入源组合成一个新输入
• 什么时候会用到：你需要同时拿“目标集合 + 编译对象”或“附加文件 + 配置”时

WithComparer(...)

• 一句话说明：自定义 provider 的变化比较规则
• 什么时候会用到：默认比较不够精确，导致不必要重算时

WithTrackingName(...)

• 一句话说明：给某个增量步骤命名，方便跟踪和调试
• 什么时候会用到：你要看“哪一步重跑了”
• 对应教程：第 12 章

关键点：

你需要知道什么	说明
它单独够不够	不够，还需要驱动打开跟踪选项
它解决什么问题	让步骤结果在 TrackedSteps 里有稳定名字

GeneratorDriverOptions

• 一句话说明：配置驱动行为的对象
• 什么时候会用到：你要打开增量步骤跟踪时

最常见的关注点：

选项	作用
trackIncrementalGeneratorSteps	是否记录步骤跟踪信息

IncrementalGeneratorRunStep

• 一句话说明：某个被跟踪步骤的一次运行记录
• 什么时候会用到：你要看这一步耗时多久、输入输出是什么

关键成员：

成员	能拿到什么
Name	步骤名
ElapsedTime	耗时
Inputs	上游输入
Outputs	本次输出及运行原因

IncrementalStepRunReason

• 一句话说明：描述这次输出为什么产生
• 什么时候会用到：你要判断是新值、修改、未变还是缓存命中

常见值：

成员	说明
New	新产生
Modified	已修改
Unchanged	未变化
Cached	直接命中缓存
Removed	已移除

最常见的跟踪链路

var trackedProvider = provider.WithTrackingName("MyStep");
var runResult = driver.GetRunResult();
var trackedSteps = runResult.Results[0].TrackedSteps;

下一步去哪里

• 想结合第 12 章看完整场景：看 advanced/01-driver-run-result.md 和 advanced/02-incremental-tracking.md
• 返回索引：看 术语与 API 手册