{
"schema": "https://ai-atoms.com/schemas/skill-v1.json",
"type": "skill",
"id": "skill/extension-points",
"version": "1.0.0",
"name": "extension-points",
"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. Only activate in MSBuild/.NET build context. 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.",
"system_prompt_fragment": "# MSBuild Extension Points\n\nHow the MSBuild pipeline provides hooks for SDKs, NuGet packages, repos, and users to inject custom logic.\n\n## CustomBefore / CustomAfter Hooks\n\nEvery major `.targets` file defines import hooks:\n\n```xml\n\n \n $(MSBuildExtensionsPath)\\v$(MSBuildToolsVersion)\\Custom.Before.Microsoft.Common.targets\n \n\n\n\n\n\n```\n\n### Rules\n\n- Default path includes version (`v$(MSBuildToolsVersion)`) for side-by-side installations.\n- Always check `Exists()`. The file may not be present on every machine.\n- **Append** to the property (don't overwrite) to chain multiple hooks:\n\n```xml\n\n \n $(CustomBeforeMicrosoftCommonTargets);$(MSBuildThisFileDirectory)MyExtension.targets\n \n\n```\n\n## Wildcard Import Directories\n\nMSBuild imports all files in extension directories, sorted alphabetically:\n\n```xml\n\n```\n\n### Key paths\n\n| Property | Resolves to | Scope |\n|---|---|---|\n| `$(MSBuildUserExtensionsPath)` | `%APPDATA%\\Microsoft\\MSBuild` | Per-user |\n| `$(MSBuildExtensionsPath)` | MSBuild install directory | Machine-wide |\n| `$(MSBuildProjectExtensionsPath)` | `obj/` directory | Per-project (NuGet) |\n\nName files with numeric prefixes for ordering: `01-first.props`, `02-second.props`.\n\n## Import Gating — Control Properties\n\nEvery wildcard import is gated by a boolean property:\n\n```xml\n\n true\n true\n\n```\n\n### Available control properties\n\n| Property | What it disables |\n|---|---|\n| `ImportDirectoryBuildProps` | Directory.Build.props auto-discovery |\n| `ImportDirectoryBuildTargets` | Directory.Build.targets auto-discovery |\n| `ImportProjectExtensionProps` | NuGet-generated `*.props` in obj/ |\n| `ImportProjectExtensionTargets` | NuGet-generated `*.targets` in obj/ |\n| `ImportByWildcardBefore*` | Machine-level ImportBefore extensions |\n| `ImportByWildcardAfter*` | Machine-level ImportAfter extensions |\n\n## NuGet Package Build Extension Layout\n\nNuGet packages inject build logic via `build/` or `buildTransitive/` folders:\n\n```text\nMyPackage/\n build/\n MyPackage.props ← imported via *.props wildcard\n MyPackage.targets ← imported via *.targets wildcard\n buildTransitive/\n MyPackage.props ← imported by transitive consumers\n MyPackage.targets\n```\n\n### Rules\n\n- File names **must match the package ID** exactly.\n- `build/` affects direct consumers only. `buildTransitive/` affects the entire dependency chain.\n- Props are imported early (before the project), targets are imported late (after the project).\n\n## Source Tree vs Packed Layout\n\nWhen 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.\n\nThree packaging mechanisms reshape the layout at pack time:\n\n1. **`.nuspec` `` mappings** — copy a single source file into multiple per-TFM targets:\n\n ```xml\n \n \n \n \n \n \n ```\n\n In the `` element, a `target` ending in `\\` is treated as a folder (filename preserved from `src`); a `target` ending in a filename renames the file.\n\n2. **`.csproj` `` metadata** on `` or `` items — same effect via SDK pack. Use one item per destination to keep the mapping unambiguous:\n\n ```xml\n \n \n \n \n ```\n\n 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.\n\n3. **SDK conventions** — `IncludeBuildOutput`, `BuildOutputTargetFolder`, `IncludeContentInPack` automatically place built outputs under `lib//` or `build//`.\n\n### Implication for reviewers\n\nA 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:\n\n```xml\n\n\n \n\n```\n\nBefore flagging an unguarded `` inside a `build//` or `buildTransitive//` folder:\n\n1. Look for `*.nuspec` in the project directory and its immediate parent directory (do not walk further up). Read every `` whose `target` matches the imported path.\n2. Read the `.csproj` for `` metadata on ``/`` items.\n3. Only flag the import if the target path is missing from **both** the source tree *and* the projected package layout.\n\nSee also `msbuild-antipatterns` AP-13 (\"NuGet package forwarders\" exception).\n\n## Import Guard Pattern\n\nThe `.targets` file ensures `.props` was imported using a guard property:\n\n```xml\n\n\n true\n\n\n\n\n```\n\nThis handles projects that only import `.targets`.\n\n## Directory.Build Discovery\n\nMSBuild walks up the directory tree to find the nearest `Directory.Build.props`:\n\n```xml\n<_DirectoryBuildPropsBasePath>\n $([MSBuild]::GetDirectoryNameOfFileAbove('$(MSBuildProjectDirectory)', 'Directory.Build.props'))\n\n```\n\nOnly the **nearest** file is discovered. Nested hierarchies must explicitly import parents:\n\n```xml\n\n\n <_ParentPropsPath>$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))\n\n\n```\n\n## Creating Your Own Extension Point\n\n```xml\n\n\n \n\n \n $(MSBuildProjectDirectory)\\MySDK.Before.targets\n $(MSBuildProjectDirectory)\\MySDK.After.targets\n \n\n \n\n \n BeforeMySDKBuild;CoreMySDKBuild;AfterMySDKBuild\n \n \n \n \n \n \n \n\n \n\n```\n\n## Common Pitfalls\n\n- **Missing `Exists()` on optional imports** causes build failures when files are absent. **Exception**: imports inside published `build//` and `buildTransitive//` 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.\n- **Overwriting Custom* properties** drops prior hooks. Append with `;` separator.\n- **NuGet package file names not matching package ID** silently skips the import.\n- **Nested Directory.Build.props** without parent import loses repo-root settings.",
"applicable_domains": [
"code",
"dotnet",
"engineering"
],
"invocation": [
"/extension-points"
],
"tags": [
"dotnet-msbuild",
"dotnet",
"csharp",
"microsoft"
],
"authored_by": "anthropics",
"source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/extension-points/SKILL.md",
"lifecycle": "stable",
"category": "dotnet",
"provenance": {
"source": "dotnet/skills",
"source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/extension-points/SKILL.md",
"author": "Microsoft / .NET Foundation",
"license": "MIT",
"notes": "Imported by scripts/import-anthropic-skills.py."
}
}