MSBuild 后续构建慢或无改动仍重建时：用…

适用于 MSBuild/.NET 项目排查二次构建慢、应跳过却执行、自定义 Target 每次运行、VS 与命令行增量行为不一致等问题。

适用场景

解决思路

1. 理解并应用 MSBuild 增量判断：为 Target 同时声明 Inputs 和 Outputs；MSBuild 会比较 Inputs 中所有文件时间戳与 Outputs 中所有文件时间戳；若每个 Output 都比每个 Input 新，则整个 Target 跳过。
2. 没有 Inputs/Outputs 的 Target 每次构建都会运行；这是默认行为，也是最常见的增量失效原因，自定义 Target 必须补上。
3. 使用 Target 的 Incremental 属性控制增量；设置 Incremental='false' 时，即使声明了 Inputs/Outputs 也强制 Target 运行。
4. 记住 MSBuild 只用文件系统最后写入时间戳，不用内容哈希；touch 文件（只更新时间戳不改内容）也会触发重建。
5. 示例：Transform Target 设置 Inputs='@(TransformFiles)' Outputs='@(TransformFiles->'$(OutputPath)%(Filename).out')' 可增量跳过；PrintMessage 无 Inputs/Outputs 会每次运行。
6. 排查 8 类常见原因：自定义 Target 缺 Inputs/Outputs。
7. 排查 8 类常见原因：Outputs 路径含易变属性（时间戳、构建号、随机 GUID），导致找不到上次输出而总是重建。
8. 排查 8 类常见原因：Target 写入未列在 Outputs 中的文件；Target 可能被跳过，但下游 Target 仍可能被触发。
9. 排查 8 类常见原因：生成文件未注册到 FileWrites；dotnet clean 不会清理，陈旧文件会干扰增量判断。
10. 排查 8 类常见原因：glob 变化；增删源文件会改变 @(Compile) 等 item 集合，这些 item 进入 Inputs 后会触发重建，这是预期行为。
11. 排查 8 类常见原因：属性变化；$(Configuration)、$(TargetFramework) 等进入 Inputs/Outputs 路径的属性变化会导致重建；Debug/Release 切换按设计是完整重建。
12. 排查 8 类常见原因：NuGet 包更新；改包版本会更新 project.assets.json 和解析后的程序集路径，改变 ResolveAssemblyReferences 与 CoreCompile 输入，触发重建。
13. 排查 8 类常见原因：构建服务器 VBCSCompiler 缓存失效；Roslyn 编译器服务器被回收（超时、崩溃或手动 kill）后，下次构建即使 MSBuild 增量检查通过也会因需重建内存缓存而变慢。
14. 用 binlog 诊断“为什么又重建”：连续构建两次并分别记录 binlog：dotnet build /bl:first.binlog；dotnet build /bl:second.binlog；第一次作基线，分析第二次。
15. 优先使用 binlog MCP（Microsoft.AITools.BinlogMcp，binlog MCP 命名空间）分析第二次 binlog。
16. 用 overview 工具检查整体构建状态和耗时。
17. 用 search 工具查找已执行与已跳过 Target：搜索 'Building target completely'、'Building target incrementally'、'Skipping target'。
18. 用 search 工具查找 'is newer than output' 消息，定位哪个输入文件触发重建。
19. 用 target_reasons、project_targets 等 target 相关工具检查特定 Target 为何运行。
20. 用 expensive_targets 工具找出第二次构建中耗时最多的 Target，作为优化对象。
21. 若 MCP 不可用，回退到文本日志 replay：dotnet msbuild second.binlog -noconlog -fl -flp:v=diag;logfile=second-full.log;performancesummary。
22. 然后搜索实际执行的 Target：grep -E 'Building target|Target.*was not skipped' second-full.log；完美增量构建中大多数 Target 应被跳过。
23. 通过诊断日志中的执行消息检查未跳过 Target，查找 'out of date' 消息判断运行原因。
24. 识别关键消息：'Building target X completely' 表示 MSBuild 未找到输出或所有输出缺失，是完整 Target 执行。
25. 识别关键消息：'Building target X incrementally' 表示部分（但非全部）输出过期。
26. 识别关键消息：'Skipping target X because all output files are up-to-date' 表示 Target 被正确跳过。
27. 搜索 'is newer than output'：grep 'is newer than output' second-full.log，找出具体输入文件的时间戳导致 Target 被视为过期。
28. 在 MSBuild Structured Log Viewer 中并排比较 first.binlog 与 second.binlog，查看变化。
29. 用 grep 'Target Performance Summary' -A 30 second-full.log 查看第二次构建中耗时最多的 Target，作为优化对象。
30. 检查仍运行但耗时为零的 Target，它们可能有导致执行的无关依赖，需要移除或修正。
31. 使用 FileWrites item 注册自定义 Target 创建的任何文件，让 dotnet clean 知道要删除；否则生成文件累积并可能干扰增量检查。
32. 对多个项目共享的生成文件使用 FileWritesShareable item；这些文件会被跟踪，但其他项目仍引用时不会被删除。
33. 若未注册 FileWrites：文件会堆积在输出和中间目录，dotnet clean 不会移除，可能导致陈旧数据或 up-to-date 检查混乱。
34. 在创建文件的 Target 内把生成文件加入 FileWrites：示例用 WriteLinesToFile 写文件，并在 ItemGroup 中添加 <FileWrites Include='$(IntermediateOutputPath)generated.cs' />。
35. 处理 Visual Studio FUTDC 与 MSBuild Inputs/Outputs 的差异：VS 有独立的 Fast Up-to-Date Check，可解释“VS 里重建但命令行不重建”。
36. VS FUTDC 更快，因为它进程内运行、检查已知 item 集合而不调用 MSBuild；它比较 Compile、Content、EmbeddedResource 等常见 item 类型的时间戳与项目主要输出。
37. 如果项目使用自定义 build action、生成文件的自定义 Target 或 FUTDC 不知道的非标准 item 类型，FUTDC 可能判断错误。
38. 可设置 <DisableFastUpToDateCheck>true</DisableFastUpToDateCheck> 禁用 FUTDC，强制 VS 使用 MSBuild 完整增量检查。
39. 诊断 FUTDC 决策：在 VS 打开 Output 窗口，进入 Tools → Options → Projects and Solutions → SDK-Style Projects，把 Up-to-date Checks 日志级别设为 Verbose 或更高；FUTDC 会记录它认为哪个文件过期。
40. 排查常见 VS FUTDC 问题：自定义 build action 未注册到 FUTDC 系统。
41. 排查常见 VS FUTDC 问题：CopyToOutputDirectory 的 item 比上次构建新。
42. 排查常见 VS FUTDC 问题：由 Target 动态添加的 item，FUTDC 不会评估。
43. 排查常见 VS FUTDC 问题：带 CopyToOutputDirectory='PreserveNewest' 的 Content 或 None item 被修改。
44. 编写完整增量自定义 Target 示例：GenerateConfig 设置 Inputs='$(MSBuildProjectFile);@(ConfigInput)'、Outputs='$(IntermediateOutputPath)config.generated.cs'、BeforeTargets='CoreCompile'；在 Target 内用 WriteLinesToFile 生成文件，并添加 FileWrites Include 与 Compile Include。
45. 在该示例中让 Inputs 包含 $(MSBuildProjectFile)，确保项目文件本身变化（如影响生成的属性被修改）时 Target 重跑。
46. 在该示例中让 Inputs 包含 @(ConfigInput)，即驱动生成的实际源文件。
47. 在该示例中让 Outputs 使用 $(IntermediateOutputPath)，生成文件进入由 MSBuild 管理的 obj/ 目录并可自动清理。
48. 在该示例中使用 BeforeTargets='CoreCompile'，确保生成文件在编译器运行前可用。
49. 在该示例中注册 FileWrites，确保 dotnet clean 会删除生成文件。
50. 在该示例中把生成文件加入 Compile，使其参与编译，而不要求在评估时文件已存在。
51. 避免常见错误：无 Inputs/Outputs 的 Target（如 BadTarget）会在每次构建运行。
52. 避免常见错误：Outputs 使用易变输出路径（如 gen_$([System.DateTime]::Now.Ticks).cs）导致永远找不到上次输出。
53. 采用正确写法：GoodTarget 使用稳定路径、注册输出，并设置 Inputs='@(Compile)'、Outputs='$(IntermediateOutputPath)generated.cs'、BeforeTargets='CoreCompile'，执行 generate-code.exe 后添加 FileWrites 与 Compile。
54. 用 /clp:PerformanceSummary 查看各 Target 和 Task 耗时：dotnet build /clp:PerformanceSummary；表格按累计时间排序，便于发现增量构建中不应运行的 Target。
55. 用 /pp:preprocess.xml 生成内联所有 import 的单个 XML，显示完整评估后的项目：dotnet msbuild /pp:preprocess.xml；搜索任意 Target 的 Inputs/Outputs 定义位置或完整 import 链。
56. 同时使用 PerformanceSummary 和 /pp，再把结果与 binlog 分析交叉参照，形成完整图景。
57. 常见修复：始终给自定义 Target 添加 Inputs 和 Outputs。
58. 常见修复：生成文件使用 $(IntermediateOutputPath)。
59. 常见修复：在 FileWrites 中注册生成文件。
60. 常见修复：避免在构建中使用易变数据；不要在文件路径或生成内容中嵌入时间戳、随机值或构建计数器，除非有管理陈旧的明确策略；如必须使用，隔离到单个文件并最小化下游影响。
61. 常见修复：需要传递 item 但不想创建增量构建依赖时，用 Returns 而不是 Outputs；Outputs 同时定义增量检查和 Target 返回值，Returns 只影响返回值，不做增量检查。
62. 示例：<Target Name='GetFiles' Outputs='@(DiscoveredFiles)'> 影响增量检查和返回值；<Target Name='GetFiles' Returns='@(DiscoveredFiles)'> 只影响返回值。

适用边界 · 注意事项

• 不适用于首次构建慢；首次构建慢应改用 build-perf-baseline 分析。
• 不适用于并行问题、评估阶段慢或非 MSBuild 构建系统；并行问题用 build-parallelism，评估阶段慢用 eval-performance，非 MSBuild 构建系统不适用本技能。