/msbuild

name: msbuild
description: "Use only for MSBuild failure investigation, build-performance analysis, or review of existing build XML/extension contracts. A plan to convert a working legacy/non-SDK project to SDK style or migrate packages.config is a project-system migration, NOT a build-file review: do not activate, even to check scope. Framework/API upgrades are also excluded. Activate for advisory Import/Exists hook and NuGet packed-import questions even without a checkout or failed build; .csproj/.fsproj/.vbproj/.props/.targets conditions; custom-target inputs/outputs; .binlog capture/replay; failing dotnet build/restore/pack/publish or MSBuild-based test builds; slow evaluation, compilation, copying, or no-change builds; and controlled timing comparisons. Exclude SDK installation alone, C# refactoring, runtime profiling, assertions after successful builds, and non-MSBuild builds."
license: MIT

MSBuild troubleshooting

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.

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 `.binlog` 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.

For 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.

1. Troubleshoot build issues

**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](references/binlog-failure-analysis.md) | 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](references/binlog-generation.md), then [failure analysis](references/binlog-failure-analysis.md) | 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](references/msbuild-antipatterns.md) | 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](references/extension-points.md) | 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](references/incremental-build.md) | 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.

2. Diagnose and improve build performance

**Goal:** measure the reported scenario, identify its bottleneck, change one cause, and compare equivalent builds without losing required behavior.

1. Reuse matching measurements. If they are missing, establish the relevant baseline before editing configuration; do not time a failed build as a successful baseline. 2. Classify evaluation versus target/task execution. Inclusive target totals and dependency waits are not additive wall time or proof of CPU utilization. 3. Follow the measured branch below. Do not apply every optimization in every reference. 4. 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](references/build-perf-baseline.md) | 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](references/build-perf-diagnostics.md) | 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](references/eval-performance.md) | Evaluation versus execution; legitimate versus accidental project instances. | | Content copies or output I/O dominate | [copy-to-output-directory](references/copy-to-output-directory.md) | 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](references/incremental-build.md) | 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 correctn