Msbuild

MSBuild troubleshooting

For advice or static review, answer from the supplied XML, package facts, or measurements when they settle the question: no reference reads, checkout discovery, commands, or invented verification. For requested work, start at the supplied project or artifact; discover only what the next decision needs. Read a reference only for a specific unresolved question. References are not invocable skills.

Start with the task and evidence

Before editing, follow repository instructions and inspect the project/imports. Preserve the original command, working directory, SDK, 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 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.

Capture only: choose an unused artifact path under the supplied workspace, unless the user specified another artifact directory. Do not put the only deliverable in a shared/global temporary directory where workspace artifact collection will miss it, or stage/commit the log. Append the binary logger to the exact supplied command, run it once, and save its original exit code before checking the new log is nonempty. Report the artifact path and original exit code, then stop: no replay, diagnosis, or repair. Read capture details only for an unresolved wrapper, logger-option, toolset, or privacy question.

1. Troubleshoot build issues

Goal: identify the independent root causes and make the smallest repair, not a broad cleanup.

For build-wiring-only work, generator and source inputs are read-only throughout, not restored after tests; edit the original only as the requested repair requires. Allocate disposable scratch as a uniquely named directory outside the project tree, normally the OS temporary directory from mktemp -d; a copy inside the project can be matched by SDK default globs and break the later confirming build. Print the path once and write every copy, log, and hash under it: no fixed leaf names, pointer files, pre-deleting, or globbing to recover it. After the checks, remove exactly that path (never a pattern) and keep it in the report. Copy the project/input tree and required imports; run every scenario that adds, deletes, empties, or retimes inputs, or deletes obj/outputs, with the copy as working directory. A backup is not a verification copy, nor is an original project already under a temporary path. Compare original hashes before/after; equal final hashes do not excuse intermediate mutation. A confirming build of the repaired original must not delete outputs. If the copy cannot reproduce the environment, report blocked checks.

For input-set changes, prefer a persisted membership list written with WriteLinesToFile and WriteOnlyWhenDifferent, plus actual files in Inputs. A path list is not a content hash. Verify first/unchanged builds, deletion, older addition, empty inputs, and missing-output recovery on the copy. End the repair report, however brief, with three labeled explanations, not only a checklist:

• Cause: state both blind spots: a deleted input vanishes from the timestamp comparison; an added input older than the output never looks newer; either skips required regeneration.

• Mechanism: identify the membership artifact and how its changes invalidate the output. Unchanged membership preserves skips; actual file timestamps still catch ordinary edits.

• Checks: list passed, failed, and not-run separately with the command or path used. "None failed" requires every command to exit 0; an errored script, even if fixed and rerun, is listed failed with its cause. If the main scenario passed but a later assertion failed, report both; never summarize as verified.

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 original workload, not an easier replacement.

For advice, give the verdict, decisive facts, and a concrete next step with equivalent successful builds and required outputs. Do not re-prove a supplied timeline or read references to restate it. Do not infer warm/no-op state or assign any part of a confounded timing gap to restore, cache, or setting effects without isolating that cause.

When a minimal attribution experiment is needed, return one two-arm table, not alternatives:

1. Bind the treatment to the user's identified setting and old/new values. If unidentified, retain literal <setting>, <old>, <new> placeholders. Differing commands are confounds, not setting names. Never substitute restore policy, Build/Rebuild, or cache state for an unidentified setting.

2. Expand the full original baseline command in both arms. Only an explicitly identified command-line treatment may change its own argument; otherwise vary its configured value.

3. Match non-treatment SDK, machine, configuration, instrumentation, target, restore policy, and input/output state exactly as supplied. Add no source edit the original workload lacked (keep one it had in both arms). Matching both arms is not enough if both replace the original workload. When they are controls, retain supplied Rebuild and timed restore; do not prime, warm, or move work outside the timer unless the original workload already did.

4. Alternate matched pairs; compare wall-time medians and observed ranges; check required outputs and diagnostics. Scope the result to that workload. The table is the only experiment; the last sentence states a validity check or residual limit, not an offer or variant.

For optimization work, establish the relevant successful baseline before changing one supported cause:

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: preserve build contracts, not implicitly migrate frameworks, packages, languages, or project systems.

Check evaluation phases, not just import order. Outside targets, properties/imports are evaluated before items. A framework set in the project body can be unavailable to an early property condition in Directory.Build.props but available to an item condition in that same file. Move only the premature property assignment after its dependency; do not relocate an intentionally project-owned framework or a working item declaration. Preserve F# compile order and inspect SDK defaults before adding switches to suppress supposedly duplicated items.

Record the existing contract; a matching catalog pattern alone is not a defect. Leave correct code alone. Validate authorized changes against original configurations, consumers, and affected build behavior.

Keep optional and required imports distinct, including inside aggregation files:

<Import Project="optional.targets" Condition="Exists('optional.targets')" />
<Import Project="required.targets" />

The required import must load or fail, not silently skip. Explain why a condition on an entire mixed path list can suppress a valid required import; semicolon-separated imports themselves are supported. Check optional present/absent crossed with required present/absent, preserving order when both exist. When checks run, report the observed order and failure cases, not only "verification passed." Do not replace configurable paths with hard-coded values unnecessarily.

For a packaged forwarder, keep these bindings separate:

Do not substitute the manifest path for a mapping's src. For a no-change verdict, explain how NuspecFile selection, NuspecBasePath src lookup, mapping, packed target, and relative import connect, and why guarding a required import would hide a broken package. If supplied package facts settle this, stop: no Exists guard, reorganization, or confirmatory rebuild/repack. Inspect artifacts only when verification is requested or contents remain unknown.

Shared evidence and safety

• 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. After a failed reference read, allow one listing of references to distinguish a missing bundled file from a present-but-unreadable tool integration failure. Report the error and reduced coverage; do not retry through shell commands or other readers, and do not pretend unread guidance was followed. Never work around a policy denial.

• 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

Advice: verdict, decisive evidence, necessary next measurement; no manufactured verification. Repository work: cause/decision, minimal change (or no change), and exact successful, failed, and not-run checks. Performance claims also need comparable measurements and uncertainty. Scale length to the task, but never drop a required report field.