扩展专题 2：增量步骤跟踪

这个专题只回答一个问题：我怎么知道“增量管道哪一步重新跑了”。

什么时候需要看这个专题

当你遇到下面这些情况时，这个专题有用：

• 你想知道到底是哪段 provider 重新计算了
• 你已经加了 WithTrackingName(...)，但不知道还缺什么
• 你想确认这次是新值、修改、未变还是缓存命中

最短理解链路

provider.WithTrackingName("StepName")
  + GeneratorDriverOptions(trackIncrementalGeneratorSteps: true)
  -> driver.GetRunResult()
  -> GeneratorRunResult.TrackedSteps
  -> IncrementalGeneratorRunStep

1. WithTrackingName(...) 只负责命名

这一步只是给某个 provider 一个稳定名字，方便你在跟踪结果里找到它。

var trackedProvider = classDeclarations.WithTrackingName("ClassDeclarations");

如果只做这一步，不打开驱动跟踪，通常还是看不到完整结果。

2. 还必须打开驱动跟踪

第二步是通过 GeneratorDriverOptions 打开 trackIncrementalGeneratorSteps。

你可以把这件事记成一句话：

• WithTrackingName(...) 负责命名
• GeneratorDriverOptions 负责记录

3. 运行后从哪里读

var runResult = driver.GetRunResult();
var generatorResult = runResult.Results[0];
var trackedSteps = generatorResult.TrackedSteps;

继续往下看时，最常见的是：

var steps = trackedSteps["ClassDeclarations"];

4. IncrementalGeneratorRunStep 最值得看什么

成员	作用
Name	这一步叫什么
ElapsedTime	这一步耗时多少
Inputs	它依赖了哪些上游输入
Outputs	输出值和运行原因

5. IncrementalStepRunReason 怎么理解

最常见的几个值：

值	含义
New	新产生
Modified	相对上次发生修改
Unchanged	没变化
Cached	直接命中缓存
Removed	上次有，这次被移除了

6. 什么时候值得看这个专题

值得看的场景：

• 你在调性能问题
• 你怀疑某一步重复计算太多
• 你在给复杂生成器做回归测试

不值得一上来就看的场景：

• 你还没跑通主案例
• 你连 .g.cs 都还没确认生成

先把基础路径走通，再来用步骤跟踪。

7. 最推荐的配套文档

• 术语解释：看 术语分册 6：驱动与跟踪
• 常见排错：看 FAQ 分册 4：测试、调试与驱动结果
• 返回主教程收口：看 第 12 章