agentsclimarketplace
Sign in

Extension points

Skill dotnet/skills/plugins/dotnet-msbuild/skills/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.From its SKILL.md

Install
npx -y skills add dotnet/skills --skill extension-points

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

11.6 KB, ~2.6k tokens by cl100k_base, as published. Nobody here has run it

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

PropertyResolves toScope
$(MSBuildUserExtensionsPath)%APPDATA%\Microsoft\MSBuildPer-user
$(MSBuildExtensionsPath)MSBuild install directoryMachine-wide
$(MSBuildProjectExtensionsPath)obj/ directoryPer-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

PropertyWhat it disables
ImportDirectoryBuildPropsDirectory.Build.props auto-discovery
ImportDirectoryBuildTargetsDirectory.Build.targets auto-discovery
ImportProjectExtensionPropsNuGet-generated *.props in obj/
ImportProjectExtensionTargetsNuGet-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:

  1. .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, a target ending in \ is treated as a folder (filename preserved from src); a target ending in a filename renames the file.

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

  3. SDK conventions — IncludeBuildOutput, BuildOutputTargetFolder, IncludeContentInPack automatically place built outputs under lib/<tfm>/ or build/<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:

  1. Look for *.nuspec in the project directory and its immediate parent directory (do not walk further up). Read every <file target=…> whose target matches the imported path.
  2. Read the .csproj for <PackagePath> metadata on <None>/<Content> items.
  3. 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 published build/<tfm>/ and buildTransitive/<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.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Keep looking

Skills are one crate of 326,144. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.