msbuild-antipatterns

Detects and fixes common anti-patterns in MSBuild project and build files.

Updated Jul 12, 2026
One-click install
npx skills add https://github.com/Patrick-Rex/DotNetTechSamples --skill msbuild-antipatterns-patrick-rex
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: msbuild-antipatterns
Source: https://github.com/Patrick-Rex/DotNetTechSamples/tree/main/.agents/plugins/dotnet-msbuild/skills/msbuild-antipatterns
Command: npx skills add https://github.com/Patrick-Rex/DotNetTechSamples --skill msbuild-antipatterns-patrick-rex

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? MSBuild project files (.csproj, .props, .targets) often accumulate subtle authoring mistakes—unquoted conditions, hardcoded paths, missing incremental-build metadata, redundant references—that cause broken builds, slow no-op builds, cross-platform failures, and flaky parallel-build file locks. This Skill provides a numbered catalog of 23 anti-patterns, each with a symptom, an explanation of why it is harmful, and a concrete BAD-to-GOOD fix. ## Core Features & Use Cases - Anti-Pattern Catalog (AP-01 to AP-23): Covers Exec misuse, unquoted conditions, hardcoded paths, restated SDK defaults, manual file listing, HintPath references, missing PrivateAssets, scattered package versions, monolithic targets, missing Inputs/Outputs, import guards, backslash paths, evaluation-phase side effects, and project-instance forking races. - Severity-Ranked Checklist: A quick-reference table orders checks by severity (error-prone, dangerous, legacy, noise) so reviewers can prioritize findings. - Deep-Dive References: Supplementary documents detail incremental build Inputs/Outputs with FileWrites registration and PrivateAssets rules for analyzer and build-tool packages. - Use Case: When asked to review a .csproj or Directory.Build.props file, scan it against the catalog and report each violation with its severity and the exact corrected XML. ## Quick Start Review my Directory.Build.props and all .csproj files in this repo for MSBuild anti-patterns and list each issue with its fix.

Frequently Asked Questions about msbuild-antipatterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a .csproj file for common mistakes?

Scan the project file against the anti-pattern catalog: check for unquoted conditions, hardcoded absolute paths, restated SDK defaults, manual Compile listings, and HintPath references. Each finding maps to a concrete BAD-to-GOOD XML fix.

Why does my MSBuild target run on every build even when nothing changed?

The target is missing Inputs and Outputs attributes, so MSBuild cannot determine it is up-to-date. Add Inputs including $(MSBuildProjectFile), Outputs pointing into $(IntermediateOutputPath), and register generated files with FileWrites.

Should analyzer packages like StyleCop use PrivateAssets?

Yes, analyzer and build-tool packages such as StyleCop.Analyzers, Microsoft.SourceLink.GitHub, and MinVer should set PrivateAssets="all". Without it, these build-time dependencies flow transitively to consumers of your library.

Why does my parallel build fail with file-in-use errors?

A likely cause is forking a project instance via the MSBuild task or SetTargetFramework metadata with path-neutral global properties, so two instances share the same output path and write the same files concurrently. Remove the redundant global property or give each instance a distinct output path.

Can I condition properties on TargetFramework in Directory.Build.props?

No, property conditions on $(TargetFramework) in .props files silently fail for single-targeting projects because the property is not yet set during early evaluation. Move such conditions to Directory.Build.targets or the project file; item and target conditions are unaffected.

When should I not use this MSBuild anti-pattern catalog?

Do not apply it to non-MSBuild build systems such as npm, Maven, or CMake. It also does not cover migrating legacy projects to SDK-style format, which is handled by a separate modernization workflow.