msbuild

MSBuild 故障排查

这是入口技能。请选择故障排查、性能或编写审查，然后 只阅读相关的本地参考资料。这些参考资料保留了原始 MSBuild 技能的内容和身份， 并修正了正确性问题；它们不是需要单独启用的技能。

从任务和证据入手

对于需要检出代码库的任务，请在当前工作区中找到相关项目/解决方案、共享构建文件、SDK 选择方式以及仓库构建说明。保留原始命令、工作目录、 配置、目标框架、运行时标识符、全局属性和目标。 只询问无法发现且会对处理产生实质影响的信息。

现有的 .binlog 可能是唯一可用的产物。请求新建构建之前，应先分析它；其中的路径并不能证明本地存在代码检出。对于可独立完成的静态审查或咨询问题，请使用提供的 XML 和相关参考资料；不要要求提供代码检出、还原、构建或 binlog。

对于混合请求，应先修复正确性问题，再测量成功构建的性能；并将编写审查与性能实验分开。构建成功后测试断言失败，并不属于 MSBuild 故障。

1. 排查构建问题

**目标：**找出彼此独立的根本原因，并进行最小范围的修复，而非大范围清理。

情况	阅读	操作
构建失败，且存在二进制日志	binlog-failure-analysis	使用 MSBuild 重放日志；将错误关联到负责的项目实例、目标和任务。区分根本原因与级联故障。
故障需要证据，但不存在匹配的日志	binlog-generation，然后阅读 故障分析	按原始调用捕获一次日志，验证产物并进行分析。
项目/构建文件中的条件、项、属性或输出路径有误	msbuild-antipatterns	选择相关目录条目，并在进行任何更改前检查其例外情况。
导入项或构建钩子缺失、被覆盖或执行顺序错误	extension-points	检查导入约定、发现顺序和打包后的 NuGet 布局，而不是掩盖必需操作的失败。
输出过期或必需工作被跳过	incremental-build	证明是哪个输入、输出、时间戳、项或条件导致判断错误。正确性优先于速度。

修复后，重新运行原先失败的场景，并检查受影响的依赖项。如果只有日志可用，请提供有证据支持的修复建议，并说明尚未应用修复或重新构建。 不要将有针对性的故障调查扩大为解决方案范围的编写清理。

2. 诊断并改善构建性能

目标： 测量报告中的场景，找出瓶颈，改变一个原因，并比较等效构建，同时不丢失所需行为。

1. 复用匹配的测量结果。如果缺少测量结果，请先建立相关基线，再编辑配置；不要把失败的构建计作成功的基线。
2. 区分评估与目标执行。包含依赖项的目标总耗时和依赖等待时间，不能相加得出墙钟时间，也不能证明 CPU 利用率。
3. 按照下方测得的分支进行处理。不要在每个场景中都套用所有参考优化。
4. 重复相同的场景、命令、输入更改和检测方式。报告波动/噪声及正确性检查；单次运行更快并不能证明有所改善。

情况	阅读	注意区分
没有可信的优化前后测量结果，或需要建立基线/进行受控优化	build-perf-baseline	冷输出、输入发生更改后的热构建和无更改构建；还原/缓存状态；普通 Build 与强制 Rebuild。
尚未确定耗时的工作，或编译器/分析器/引用/还原耗时占主导	build-perf-diagnostics	实际任务耗时与编排等待时间、重叠耗时，以及缺失的检测数据。
耗时发生在目标执行前的 glob、导入或属性评估阶段	eval-performance	评估与执行；合理与意外的项目实例。
内容复制或输出 I/O 占主导	copy-to-output-directory	复制模式/版本支持、未更改的副本，以及对已修改目标的预期处理方式。
第二次无更改构建仍会重新编译/生成，或增量行为异常	incremental-build	预期的失效与跟踪缺失；已更改/新增/已移除的输入，以及缺失的输出。

如果证据不支持所怀疑的瓶颈、结果处于噪声范围内，或正确性退化，请停止。报告缺失的测量数据，不要凭空编造完整基线。

3. 审查构建编写方式

目标： 在保留行为的同时，改进项目/构建文件结构和扩展契约。本流程指 MSBuild 编写方式清理，不包括隐式的框架、包、语言或旧版项目系统迁移。

请求的更改	阅读	保留
审查/清理项目文件、共享属性、项声明或自定义目标	msbuild-antipatterns	有意的覆盖、F# 源文件顺序、必需的导入、包资产，以及实际的输入/输出契约。
审查/改进钩子、导入、共享文件发现或 NuGet 构建扩展	extension-points	现有钩子、评估顺序、直接/传递使用者行为，以及打包后的布局。
将生成或复制流程重构作为清理的一部分	视情况阅读 incremental-build 和 copy-to-output-directory	首次构建和无更改时的行为、失效、生成项注册，以及输出完整性。

编辑前记录现有契约。仅审查相关目录条目；文本模式匹配并不能证明存在缺陷。保持已经正确的模式不变。验证原始配置、相关使用者，以及受影响的增量构建/打包/发布行为。

共享证据与安全

• 对于仅捕获的请求，使用 binlog-generation，报告新生成的产物和原始退出代码，然后停止。对于分析，使用 MSBuild 回放，切勿解析二进制文件文本。回放成功与回放耗时并不代表记录中的构建结果或耗时。
• 相对于此技能解析这些文件。不要加载原始插件的技能，也不要搜索其他安装目录或检出版本。如果缺少捆绑的参考文件，可以列出一次 references，报告缺失项，不要声称已遵循其中的指导。
• 不要清理输出或缓存、停止共享构建服务器、禁用诊断、更改 SDK，也不要将构建串行化作为通用修复。将任何必要的破坏性实验限定在获准且由你负责的输出范围内。除非已获准共享，否则请将二进制日志和回放日志保留在本地。
• 区分记录的事实与假设。必须明确报告缺失的源代码、日志详情、工具或平台支持，不要用假定值或捏造的验证结果替代。

完成

返回所选任务、原因或瓶颈，或作者决策，提供支持证据，并说明所做或建议的最小改动。若无需改动，也要说明。准确列出验证内容和结果，区分成功、失败和未运行的检查；性能工作还需提供可比较的测量结果和不确定性。回复详略应与任务相称。