msbuild
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMSBuild troubleshooting
MSBuild 故障排查
This is the entry skill. Choose troubleshooting, performance, or authoring review, then
read only the relevant local references. The references retain the content and identities of
the original MSBuild skills, with correctness fixes; they are not separate skills to activate.
这是入口 skill。选择 troubleshooting、performance 或 authoring review，然后
仅阅读相关的本地 references。这些 references 保留了原始 MSBuild skills 的内容和标识，并包含正确性修复；
它们不是需要单独激活的 skills。
Start with the task and evidence
从任务和证据开始
For tasks that need a checkout, discover the relevant project/solution, shared build files, SDK
selection, and repository build instructions in the current workspace. Preserve the original command, working directory,
configuration, target framework, runtime identifier, global properties, and target.
Ask only for consequential information that cannot be discovered.
An existing can be the only available artifact. Analyze it before requesting a new
build; paths inside it do not prove a checkout exists locally. For a self-contained static review
or advisory question, use the supplied XML and relevant references; do not require a checkout,
restore, build, or binlog.
.binlogFor a mixed request, fix correctness before measuring successful builds, and keep authoring review
separate from a performance experiment. A failing test assertion after a successful build is not
an MSBuild failure.
对于需要 checkout 的任务，在当前 workspace 中查找相关 project/solution、共享 build files、SDK
selection 和 repository build instructions。保留原始 command、working directory、
configuration、target framework、runtime identifier、global properties 和 target。
仅询问无法发现且会影响结论的信息。
现有的 可能是唯一可用的 artifact。在请求新的 build 前先分析它；其中的 paths
并不能证明本地存在 checkout。对于自包含的静态审查或咨询问题，使用提供的 XML 和相关 references；
无需 checkout，也不要求执行 restore、build 或提供 binlog。
.binlog对于混合请求，先修复正确性问题，再测量成功的 builds，并将 authoring review 与 performance
experiment 分开。成功 build 后的 test assertion 失败不属于 MSBuild failure。
1. Troubleshoot build issues
1. 排查构建问题
Goal: identify the independent root causes and make the smallest repair, not a broad cleanup.
| Situation | Read | Action |
|---|---|---|
| A build failed and a binary log exists | binlog-failure-analysis | Replay the log with MSBuild; connect errors to the responsible project instance, target, and task. Separate root causes from cascading failures. |
| The failure needs evidence and no matching log exists | binlog-generation, then failure analysis | Capture the original invocation once, verify the artifact, and analyze it. |
| A project/build file has incorrect conditions, items, properties, or output paths | msbuild-antipatterns | Select the relevant catalog entries and check their exceptions before changing anything. |
| Imports or build hooks are missing, overwritten, or run in the wrong order | extension-points | Inspect the import contract, discovery order, and packed NuGet layout rather than hiding a required failure. |
| Outputs are stale or required work is skipped | incremental-build | Prove which input, output, timestamp, item, or condition makes the decision wrong. Correctness takes priority over speed. |
After a repair, rerun the original failing scenario and check affected dependents. If only a log
is available, provide an evidence-backed proposed fix and say it was not applied or rebuilt.
Do not turn a targeted failure investigation into solution-wide authoring cleanup.
目标： 识别彼此独立的根因，并实施最小修复，而不是进行大范围清理。
| 情况 | 阅读 | 操作 |
|---|---|---|
| 构建失败且存在 binary log | binlog-failure-analysis | 使用 MSBuild 重放该 log；将错误关联到对应的 project instance、target 和 task。区分根因与级联失败。 |
| 故障需要证据，但没有匹配的 log | binlog-generation，然后阅读 failure analysis | 仅捕获一次原始 invocation，验证 artifact，然后分析它。 |
| project/build file 的 conditions、items、properties 或 output paths 不正确 | msbuild-antipatterns | 选择相关目录条目，并在修改任何内容前检查其中的例外情况。 |
| imports 或 build hooks 缺失、被覆盖或以错误顺序运行 | extension-points | 检查 import contract、discovery order 和 packed NuGet layout，而不是掩盖必需失败。 |
| outputs 陈旧，或必需工作被跳过 | incremental-build | 证明究竟是哪个 input、output、timestamp、item 或 condition 导致决策错误。正确性优先于速度。 |
修复后，重新运行原始失败场景，并检查受影响的 dependents。如果只有 log 可用，
请提供有证据支持的 proposed fix，并说明未应用或重新构建。
不要将针对性故障调查扩展为整个 solution 范围的 authoring cleanup。
2. Diagnose and improve build performance
2. 诊断并改进构建性能
Goal: measure the reported scenario, identify its bottleneck, change one cause, and compare
equivalent builds without losing required behavior.
- Reuse matching measurements. If they are missing, establish the relevant baseline before editing configuration; do not time a failed build as a successful baseline.
- Classify evaluation versus target/task execution. Inclusive target totals and dependency waits are not additive wall time or proof of CPU utilization.
- Follow the measured branch below. Do not apply every optimization in every reference.
- Repeat the same scenario, command, input change, and instrumentation. Report spread/noise and correctness checks; an isolated faster run is not proof of improvement.
| Situation | Read | Keep distinct |
|---|---|---|
| No trustworthy before/after measurements, or a baseline/controlled optimization is requested | build-perf-baseline | Cold-output, warm changed-input, and no-change builds; restore/cache state; ordinary Build versus forced Rebuild. |
| The expensive work is not yet identified, or compiler/analyzer/reference/restore time dominates | build-perf-diagnostics | Actual task cost versus orchestration waits, overlapping durations, and missing instrumentation. |
| Time is spent before target execution, in globs, imports, or property evaluation | eval-performance | Evaluation versus execution; legitimate versus accidental project instances. |
| Content copies or output I/O dominate | copy-to-output-directory | Copy mode/version support, unchanged copies, and the intended handling of a modified destination. |
| A second unchanged build recompiles/regenerates, or incremental behavior is broken | incremental-build | Expected invalidation versus missing tracking; changed/added/removed inputs and missing outputs. |
Stop when the suspected bottleneck is not supported by evidence, results fall within noise, or
correctness regresses. Report missing measurements rather than manufacturing a complete baseline.
目标： 测量所报告的场景，识别瓶颈，只改变一个原因，并在不丢失必需行为的情况下比较
等价 builds。
- 复用匹配的测量结果。如果缺少测量结果，请在修改 configuration 前建立相关 baseline；不要将 failed build 的耗时当作 successful baseline。
- 区分 evaluation 与 target/task execution。包含依赖项的 target 总计和 dependency waits 既不是可相加的 wall time，也不是 CPU utilization 的证据。
- 沿测量结果对应的分支处理。不要对每份 reference 都应用全部 optimizations。
- 重复相同的 scenario、command、input change 和 instrumentation。报告 spread/noise 和 correctness checks； 单次运行更快并不能证明有所改进。
| 情况 | 阅读 | 需区分 |
|---|---|---|
| 缺少可信的前后测量，或要求建立 baseline/进行受控优化 | build-perf-baseline | 冷输出、输入变化后的热构建和无变更构建；restore/cache 状态；普通 Build 与强制 Rebuild。 |
| 尚未定位高开销工作，或 compiler/analyzer/reference/restore 耗时占主导 | build-perf-diagnostics | 实际 task 成本与 orchestration 等待时间、重叠耗时及缺失 instrumentation 之间的区别。 |
| 时间消耗在 target execution 之前，或 globs、imports、property evaluation 中 | eval-performance | evaluation 与 execution；合理与意外产生的 project instances。 |
| 内容复制或 output I/O 占主导 | copy-to-output-directory | 复制模式/版本支持、未变更文件的复制，以及对已修改目标的预期处理方式。 |
| 第二次 unchanged build 仍会 recompile/regenerate，或 incremental behavior 已损坏 | incremental-build | expected invalidation 与 missing tracking；已变更/新增/移除的 inputs 和 missing outputs。 |
当疑似瓶颈缺乏证据支持、结果差异处于噪声范围内或正确性发生回退时停止。
报告缺失的测量结果，而不是人为拼凑出一套完整的 baseline。
3. Review build authoring
3. 审查构建编写
Goal: improve project/build-file structure and extension contracts while preserving behavior.
This route means MSBuild authoring cleanup, not an implicit framework, package, language,
or legacy project-system migration.
| Requested change | Read | Preserve |
|---|---|---|
| Review/clean up project files, shared properties, item declarations, or custom targets | msbuild-antipatterns | Intentional overrides, F# source order, required imports, package assets, and actual input/output contracts. |
| Review/improve hooks, imports, shared-file discovery, or NuGet build extensions | extension-points | Prior hooks, evaluation order, direct/transitive consumer behavior, and the packed layout. |
| Restructure generation or copying as part of cleanup | incremental-build and copy-to-output-directory, as applicable | First-build and no-change behavior, invalidation, generated-item registration, and output completeness. |
Record the existing contract before editing. Review only relevant catalog entries; a matching text
pattern is not proof of a defect. Leave already-correct patterns unchanged. Validate the original
configurations, relevant consumers, and affected incremental/pack/publish behavior.
目标： 在保留 behavior 的同时，改进 project/build-file structure 和 extension contracts。
此路径表示 MSBuild authoring cleanup，而不是隐含的 framework、package、language
或 legacy project-system migration。
| 请求的更改 | 阅读 | 保留 |
|---|---|---|
| 审查/清理 project files、shared properties、item declarations 或 custom targets | msbuild-antipatterns | 有意设置的 overrides、F# source order、必需 imports、package assets，以及实际 input/output contracts。 |
| 审查/改进 hooks、imports、shared-file discovery 或 NuGet build extensions | extension-points | 前置 hooks、evaluation order、direct/transitive consumer behavior，以及 packed layout。 |
| 在 cleanup 过程中重构 generation 或 copying | incremental-build 和 copy-to-output-directory，视情况而定 | 首次构建和无变更行为、invalidation、generated-item registration 和 output completeness。 |
编辑前记录现有 contract。仅审查相关目录条目；匹配的 text pattern 不是缺陷的证据。
保持已经正确的 patterns 不变。验证原始 configurations、相关 consumers，以及受影响的 incremental/pack/publish behavior。
Shared evidence and safety
共享证据与安全性
- For capture-only requests, use binlog-generation, report the new artifact and original exit code, and stop. For analysis, use MSBuild replay, never binary-file text parsing. Replay success and replay duration are not the recorded build's result or duration.
- Resolve these files relative to this skill. Do not load the original plugin's skills or search
other installations/checkouts. If a bundled reference is missing, allow one listing of
, report the gap, and do not pretend its guidance was followed.
references - Do not clean outputs/caches, stop shared build servers, disable diagnostics, change SDKs, or serialize builds as generic fixes. Scope any necessary destructive experiment to approved, owned outputs. Keep binary and replayed logs local unless sharing is authorized.
- Distinguish recorded facts from hypotheses. Missing source, log detail, tools, or platform support must be reported explicitly, not replaced with assumed values or invented verification.
- 对于仅捕获的请求，使用 binlog-generation，报告新的 artifact 和原始 exit code，然后停止。对于分析，使用 MSBuild replay，绝不以文本方式解析 binary file。Replay 成功和 replay 时长并不代表所记录 build 的结果或时长。
- 相对于此 skill 解析这些文件。不要加载原 plugin 的 skills，也不要搜索其他 installations/checkouts。
如果 bundled reference 缺失，允许对 执行一次列举，报告缺口，并且不要假装已遵循其指导。
references - 不要将清理 outputs/caches、停止 shared build servers、禁用 diagnostics、更改 SDKs 或串行化 builds 作为通用修复。将任何必要的破坏性 experiment 限定在已批准且由你拥有的 outputs 中。除非已获授权共享， 否则将 binary 和 replayed logs 保留在本地。
- 区分 recorded facts 与 hypotheses。缺失的 source、log detail、tools 或 platform support 必须明确报告， 不能用 assumed values 或 invented verification 替代。
Completion
完成
Return the selected task, the cause/bottleneck or authoring decision, supporting evidence,
and the minimal change made or proposed. State when no change is needed. Give the exact
verification and result, distinguishing successful, failed, and not-run checks; performance work
also needs comparable measurements and uncertainty. Keep the response proportional to the task.
返回所选任务、原因/瓶颈或编写决策、支撑证据，以及已实施或拟议的最小改动。
说明何时无需更改。给出准确的验证和结果，并区分成功、失败和未运行的检查；性能工作
还需要可比较的测量结果和不确定性。响应应与任务规模相称。