msbuild

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

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

3. Review build authoring

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.

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 references, report the gap, and do not pretend its guidance was followed.
• 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.

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.