extension-points
Guide for MSBuild extensibility: CustomBefore/CustomAfter hooks, wildcard imports with alphabetic ordering, import gating with control properties, NuGet package build extension layout (build/buildTransitive), and the MicrosoftCommonPropsHasBeenImported guard. USE FOR: diagnosing and fixing MSBuild import and hook patterns, reviewing and fixing extension point anti-patterns in Directory.Build files, fixing missing Exists() guards on imports that break fresh clones, fixing NuGet package hooks being silently dropped instead of appended, making build targets extensible for other projects, injecting custom logic into the build pipeline, creating NuGet packages that extend the build, conditionally disabling imports. DO NOT USE FOR: target authoring patterns (use target-authoring), props vs targets placement (use directory-build-organization), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.
- License 许可
- MIT
- 最近更新
- 2026-09-18
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- extension-points
- license
- MIT
- description
- Guide for MSBuild extensibility: CustomBefore/CustomAfter hooks, wildcard imports with alphabetic ordering, import gating with control properties, NuGet package build extension layout (build/buildTransitive), and the MicrosoftCommonPropsHasBeenImported guard. USE FOR: diagnosing and fixing MSBuild import and hook patterns, reviewing and fixing extension point anti-patterns in Directory.Build files, fixing missing Exists() guards on imports that break fresh clones, fixing NuGet package hooks being silently dropped instead of appended, making build targets extensible for other projects, injecting custom logic into the build pipeline, creating NuGet packages that extend the build, conditionally disabling imports. DO NOT USE FOR: target authoring patterns (use target-authoring), props vs targets placement (use directory-build-organization), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.
03 SKILL.md 正文
MSBuild Extension Points
How the MSBuild pipeline provides hooks for SDKs, NuGet packages, repos, and users to inject custom logic.
CustomBefore / CustomAfter Hooks
Every major .targets file defines import hooks:
<PropertyGroup>
<CustomBeforeMicrosoftCommonTargets Condition="'$(CustomBeforeMicrosoftCommonTargets)' == ''">
$(MSBuildExtensionsPath)\v$(MSBuildToolsVersion)\Custom.Before.Microsoft.Common.targets
</CustomBeforeMicrosoftCommonTargets>
</PropertyGroup>
<Import Project="$(CustomBeforeMicrosoftCommonTargets)"
Condition="'$(CustomBeforeMicrosoftCommonTargets)' != '' and Exists('$(CustomBeforeMicrosoftCommonTargets)')"/>
<!-- ... core targets ... -->
<Import Project="$(CustomAfterMicrosoftCommonTargets)"
Condition="'$(CustomAfterMicrosoftCommonTargets)' != '' and Exists('$(CustomAfterMicrosoftCommonTargets)')"/>
Rules
- Default path includes version (
v$(MSBuildToolsVersion)) for side-by-side installations. - Always check
Exists(). The file may not be present on every machine. - Append to the property (don't overwrite) to chain multiple hooks:
<PropertyGroup>
<CustomBeforeMicrosoftCommonTargets>
$(CustomBeforeMicrosoftCommonTargets);$(MSBuildThisFileDirectory)MyExtension.targets
</CustomBeforeMicrosoftCommonTargets>
</PropertyGroup>
Wildcard Import Directories
MSBuild imports all files in extension directories, sorted alphabetically:
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Imports\Microsoft.Common.props\ImportBefore\*"
Condition="'$(ImportByWildcardBeforeMicrosoftCommonProps)' == 'true'
and Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Imports\Microsoft.Common.props\ImportBefore')" />
Key paths
| Property | Resolves to | Scope |
|---|---|---|
$(MSBuildUserExtensionsPath) |
%APPDATA%\Microsoft\MSBuild |
Per-user |
$(MSBuildExtensionsPath) |
MSBuild install directory | Machine-wide |
$(MSBuildProjectExtensionsPath) |
obj/ directory |
Per-project (NuGet) |
Name files with numeric prefixes for ordering: 01-first.props, 02-second.props.
Import Gating — Control Properties
Every wildcard import is gated by a boolean property:
<PropertyGroup>
<ImportByWildcardBeforeMicrosoftCommonProps
Condition="'$(ImportByWildcardBeforeMicrosoftCommonProps)' == ''">true</ImportByWildcardBeforeMicrosoftCommonProps>
<ImportDirectoryBuildProps
Condition="'$(ImportDirectoryBuildProps)' == ''">true</ImportDirectoryBuildProps>
</PropertyGroup>
Available control properties
| Property | What it disables |
|---|---|
ImportDirectoryBuildProps |
Directory.Build.props auto-discovery |
ImportDirectoryBuildTargets |
Directory.Build.targets auto-discovery |
ImportProjectExtensionProps |
NuGet-generated *.props in obj/ |
ImportProjectExtensionTargets |
NuGet-generated *.targets in obj/ |
ImportByWildcardBefore* |
Machine-level ImportBefore extensions |
ImportByWildcardAfter* |
Machine-level ImportAfter extensions |
NuGet Package Build Extension Layout
NuGet packages inject build logic via build/ or buildTransitive/ folders:
MyPackage/
build/
MyPackage.props ← imported via *.props wildcard
MyPackage.targets ← imported via *.targets wildcard
buildTransitive/
MyPackage.props ← imported by transitive consumers
MyPackage.targets
Rules
- File names must match the package ID exactly.
build/affects direct consumers only.buildTransitive/affects the entire dependency chain.- Props are imported early (before the project), targets are imported late (after the project).
Forwarding chain: buildTransitive/ → build/ → shared
Forward buildTransitive/*.props and buildTransitive/*.targets through their sibling build/*.props / build/*.targets files (chain buildTransitive → build → shared) instead of importing buildMultiTargeting/ directly. This keeps build/ as the single source of truth with a clear ownership chain, so transitive consumers stay in sync with direct consumers instead of the two layouts drifting apart.
When build/ is packed per-TFM (build/<tfm>/, via TfmSpecificPackageFile, a per-TFM <PackagePath>, or SDK conventions) while buildMultiTargeting/ is not, a buildTransitive/<tfm>/ forwarder must include the TFM segment — dropping it resolves to a non-existent package-root build/MyPackage.props and fails transitive consumers with MSB4019. Derive the segment from the file's own folder, never $(TargetFramework) (NuGet nearest-match can serve a net10.0 consumer the net9.0 folder, so $(TargetFramework) may name a folder that was never restored):
<!-- buildTransitive/<tfm>/MyPackage.props -->
<Import Project="$(MSBuildThisFileDirectory)..\..\build\$([System.IO.Path]::GetFileName($([System.IO.Path]::GetDirectoryName('$(MSBuildThisFileDirectory)'))))\MyPackage.props" />
Source Tree vs Packed Layout
When reviewing a NuGet build-extension package, the source layout in the repository can legitimately differ from the packed layout inside the produced .nupkg. This is a common source of false-positive "import points at a missing file" findings.
Three packaging mechanisms reshape the layout at pack time:
-
.nuspec<file src=… target=…>mappings — copy a single source file into multiple per-TFM targets:<!-- Source tree has ONE shared file: buildTransitive\common\MyAdapter.props Pack rewrites it to per-TFM targets inside the .nupkg: buildTransitive\net462\MyAdapter.props buildTransitive\net8.0\MyAdapter.props buildTransitive\net9.0\MyAdapter.props --> <files> <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net462\MyAdapter.props" /> <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net8.0\MyAdapter.props" /> <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net9.0\MyAdapter.props" /> </files>In the
<file>element, atargetending in\is treated as a folder (filename preserved fromsrc); atargetending in a filename renames the file. -
.csproj<PackagePath>metadata on<None Update=…>or<Content Include=…>items — same effect via SDK pack. Use one item per destination to keep the mapping unambiguous:<ItemGroup> <None Include="buildTransitive\common\MyAdapter.props" Pack="true" PackagePath="buildTransitive\net8.0\MyAdapter.props" /> <None Include="buildTransitive\common\MyAdapter.props" Pack="true" PackagePath="buildTransitive\net9.0\MyAdapter.props" /> </ItemGroup>NuGet/SDK pack also accepts a semicolon-separated list (
PackagePath="buildTransitive\net8.0\;buildTransitive\net9.0\") to fan one source out to multiple destinations, but the multi-item form above is harder to misread. -
SDK conventions —
IncludeBuildOutput,BuildOutputTargetFolder,IncludeContentInPackautomatically place built outputs underlib/<tfm>/orbuild/<tfm>/.
Implication for reviewers
A forwarder like the following inside a packed build/net462/ folder is not a "missing-file" bug, even if the source tree has no buildTransitive/net462/ directory:
<!-- In packed build/net462/MyAdapter.props -->
<Project>
<Import Project="$(MSBuildThisFileDirectory)..\..\buildTransitive\net462\MyAdapter.props" />
</Project>
Before flagging an unguarded <Import> inside a build/<tfm>/ or buildTransitive/<tfm>/ folder:
- Look for
*.nuspecin the project directory and its immediate parent directory (do not walk further up). Read every<file target=…>whosetargetmatches the imported path. - Read the
.csprojfor<PackagePath>metadata on<None>/<Content>items. - Only flag the import if the target path is missing from both the source tree and the projected package layout.
See also msbuild-antipatterns AP-13 ("NuGet package forwarders" exception).
Import Guard Pattern
The .targets file ensures .props was imported using a guard property:
<!-- End of Microsoft.Common.props -->
<PropertyGroup>
<MicrosoftCommonPropsHasBeenImported>true</MicrosoftCommonPropsHasBeenImported>
</PropertyGroup>
<!-- Top of Microsoft.Common.CurrentVersion.targets -->
<Import Project="Microsoft.Common.props"
Condition="'$(MicrosoftCommonPropsHasBeenImported)' != 'true'" />
This handles projects that only import .targets.
Directory.Build Discovery
MSBuild walks up the directory tree to find the nearest Directory.Build.props:
<_DirectoryBuildPropsBasePath>
$([MSBuild]::GetDirectoryNameOfFileAbove('$(MSBuildProjectDirectory)', 'Directory.Build.props'))
</_DirectoryBuildPropsBasePath>
Only the nearest file is discovered. Nested hierarchies must explicitly import parents:
<!-- src/Directory.Build.props -->
<PropertyGroup>
<_ParentPropsPath>$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))</_ParentPropsPath>
</PropertyGroup>
<Import Project="$(_ParentPropsPath)" Condition="'$(_ParentPropsPath)' != ''" />
Creating Your Own Extension Point
<!-- MySDK.targets -->
<Project>
<Import Project="MySDK.props" Condition="'$(MySDKPropsImported)' != 'true'" />
<PropertyGroup>
<CustomBeforeMySDK Condition="'$(CustomBeforeMySDK)' == ''">$(MSBuildProjectDirectory)\MySDK.Before.targets</CustomBeforeMySDK>
<CustomAfterMySDK Condition="'$(CustomAfterMySDK)' == ''">$(MSBuildProjectDirectory)\MySDK.After.targets</CustomAfterMySDK>
</PropertyGroup>
<Import Project="$(CustomBeforeMySDK)" Condition="Exists('$(CustomBeforeMySDK)')" />
<PropertyGroup>
<MySDKBuildDependsOn>BeforeMySDKBuild;CoreMySDKBuild;AfterMySDKBuild</MySDKBuildDependsOn>
</PropertyGroup>
<Target Name="MySDKBuild" DependsOnTargets="$(MySDKBuildDependsOn)" />
<Target Name="BeforeMySDKBuild" />
<Target Name="AfterMySDKBuild" />
<Target Name="CoreMySDKBuild">
<!-- implementation -->
</Target>
<Import Project="$(CustomAfterMySDK)" Condition="Exists('$(CustomAfterMySDK)')" />
</Project>
Common Pitfalls
- Missing
Exists()on optional imports causes build failures when files are absent. Exception: imports inside publishedbuild/<tfm>/andbuildTransitive/<tfm>/folders of a NuGet package are a package contract — the target is guaranteed by the packed layout (see "Source Tree vs Packed Layout" above). Don't guard them and don't flag them. - Overwriting Custom properties* drops prior hooks. Append with
;separator. - NuGet package file names not matching package ID silently skips the import.
- Nested Directory.Build.props without parent import loses repo-root settings.
04 同仓库更多 Skills
vectorization
Design, implement, optimize, and review SIMD code in .NET. USE FOR: vectorizing scalar loops with TensorPrimitives, Vector64/128/256/512, or platform hardware intrinsics; reviewing existing SIMD code, including Vector<T>, for contract equivalence, tail handling, memory safety, portability, fallbacks, and measured performance. DO NOT USE FOR: performance work unrelated to SIMD or vectorization.
resolve-project-references
Guide for interpreting ResolveProjectReferences time in MSBuild performance summaries. Activate when ResolveProjectReferences appears as the most expensive target and developers are trying to optimize it directly. Explains that the reported time includes wait time for dependent project builds and is misleading. Guides users to focus on task self-time instead. Do not activate for general build performance -- use build-perf-diagnostics instead.
optimizing-ef-core-queries
Optimize and improve the performance of slow Entity Framework Core (EF Core) queries: make them generate less SQL, make fewer database round-trips, and return results faster. Use whenever an EF Core or DbContext query or data-access path is slow or should be made faster — whether or not EF Core owns the database schema. For EF Core, not Dapper or raw ADO.NET.
microbenchmarking
Activate this skill when BenchmarkDotNet (BDN) is involved in the task — creating, running, configuring, or reviewing BDN benchmarks. Also activate when microbenchmarking .NET code would be useful and BenchmarkDotNet is the likely tool. Consider activating when answering a .NET performance question requires measurement and BenchmarkDotNet may be needed. Covers microbenchmark design, BDN configuration and project setup, how to run BDN microbenchmarks efficiently and effectively, and using BDN for side-by-side performance comparisons. Do NOT use for profiling/tracing .NET code (dotnet-trace, PerfView), production telemetry, or load/stress testing (Crank, k6).
incremental-build
Guide for optimizing MSBuild incremental builds. USE FOR: builds slower than expected on subsequent runs, 'nothing changed but it rebuilds anyway', diagnosing why targets re-execute unnecessarily, fixing broken no-op builds. Covers 8 common causes: missing Inputs/Outputs on custom targets, volatile properties in output paths (timestamps/GUIDs), file writes outside tracked Outputs, missing FileWrites registration, glob changes, Visual Studio Fast Up-to-Date Check (FUTDC) issues. Key diagnostic: look for 'Building target completely' vs 'Skipping target' in binlog. DO NOT USE FOR: first-time build slowness (use build-perf-baseline), parallelism issues (use build-parallelism), evaluation-phase slowness (use eval-performance), non-MSBuild build systems.
eval-performance
Guide for diagnosing and improving MSBuild project evaluation performance. USE FOR: builds slow before any compilation starts, high evaluation time in binlog analysis, expensive glob patterns walking large directories (node_modules, .git, bin/obj), deep import chains (>20 levels), preprocessed output >10K lines indicating heavy evaluation, property functions with file I/O ($([System.IO.File]::ReadAllText(...))), multiple evaluations per project. Covers the 5 MSBuild evaluation phases, glob optimization via DefaultItemExcludes, import chain analysis with /pp preprocessing. DO NOT USE FOR: compilation-time slowness (use build-perf-diagnostics), incremental build issues (use incremental-build), non-MSBuild build systems.