build-dotnet · git:20261108.c2f94bf · 2026-11-08 · sha256 3b328c76683913a7
build-dotnet git:20261108.c2f94bfA
Immutable. This exact content never changes and is served at /api/v1/blob/3b328c76683913a7.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_kot34xcl3kpzjzem/3b328c76683913a7f25bbc39c53c1aa01881c3dd9056d60980de62b425f1e943.json
Then /plugin install build-dotnet@markdownregistry-kot34xcl3kpzjzem in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: build-dotnet
description: >-
How a .NET repository is built, versioned and restored — the house
conventions on top of MSBuild and NuGet. Use when creating a repo or a
project, editing Directory.Build.props, Directory.Packages.props or a
.csproj, adding or bumping a package, versioning a release, packing a
library, configuring the private feed, or when a restore or a build fails
on the audit gate. It encodes: the three-tier Directory.Build.props, one
VersionPrefix per repo (and the separately released piece that keeps its
own), Central Package Management, a three-day minimum age for third-party
versions, the NuGet vulnerability audit as a build gate, global.json,
packing metadata for libraries, and a nuget.config that holds no
credentials.
---
# Building .NET repositories
The conventions every repo follows; how MSBuild itself works is the `dotnet-msbuild` skill's (from the dotnet/skills marketplace, not this one). Code style and its gates are `code-style-dotnet`'s.
## Directory.Build.props — three tiers
- **Root** — what every project shares:
- the repo's identity (`Authors`, `Company`, `Copyright`, `RepositoryUrl`, `RepositoryType`) and the **`VersionPrefix`**;
- `TargetFramework`, `ImplicitUsings`, `Nullable`, `AnalysisLevel latest`, `EnforceCodeStyleInBuild`, `TreatWarningsAsErrors`;
- `IsPackable false` by default — a project packs only by saying so;
- the vulnerability audit (below).
- **`src/`** — only where `src` packs (a library): imports the root, then the package output — `GenerateDocumentationFile` (on for a library with outside consumers; a contracts repo turns it off on purpose, see `code-style-dotnet`), icon, readme, license, SourceLink (`Microsoft.SourceLink.GitHub`), symbols (`snupkg`), `Deterministic`, `ContinuousIntegrationBuild` on CI, and the files packed into every package.
- **`test/`** — imports the root, then the test settings (see `testing-dotnet`).
- Each lower tier starts with `<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />` — a `Directory.Build.props` does not inherit the one above on its own.
- **A `.csproj` declares only what is its own**: references, and for a package its `Description` / `PackageTags`. Everything else is inherited — a property repeated in a project is a property that will drift.
- Comment each `PropertyGroup` with what it is for; `.props` and `.csproj` are indented with tabs.
## Versions
- **One `VersionPrefix`, in the root props**, versions what the repo delivers — the service's image, or every package of a library at once (lockstep). No project sets `<Version>`: it would override the prefix.
- **A piece released on its own cycle** — the contracts, a read model (`<Service>.Query`) — lives in a repository of its own, with its own root `VersionPrefix`; a service repo never carries a second version inside it.
- SemVer: a feature is a minor, anything a consumer cannot see (tests, docs, a dependency bump) a patch, a breaking change a major. A version on the feed is never published twice.
## Central Package Management
- `Directory.Packages.props` with `ManagePackageVersionsCentrally=true`: every version — third-party, the house libraries, the contracts — is a `<PackageVersion>` there, **alphabetical**. A `.csproj` references packages **without** a version.
- Projects inside the repo reference each other with `ProjectReference`, never through CPM.
- Keep the house libraries' versions in step across repos; a stale transitive dependency is caught by the audit, not by a reviewer.
## Updating packages — a minimum release age
- **A third-party version lands only once it is three days old.** A trojanized release from a hijacked account is typically detected and pulled within that window — the same rule `pnpm` applies with `minimumReleaseAge`, but NuGet has no setting for it, so it is applied at bump time: the version's date is on its nuget.org page, or `published` in `https://api.nuget.org/v3/registration5-semver1/<id>/<version>.json` (the id lowercase).
- **Exempt: the packages you or your organization publish** — your own libraries and your contracts land the day they ship.
- **Exempt: the fix for a known vulnerability** — one the audit already raises, or one the publisher's release notes announce as a security fix before the advisory database lists it (Microsoft's monthly .NET patches name their CVEs). A known vulnerability outweighs the hypothetical risk of a fresh version: take the fix the day it ships, and note why it skipped the wait.
- **The wait is the default, not a lock.** Any other case that cannot wait is a decision someone takes, with its reason written in the commit — never a silent bump.
- A dependency releasing patches in quick succession is the case the wait exists for: the next day's patch often fixes today's.
- `dotnet list <solution> package --outdated` lists what can move; every candidate still goes through the age check.
## The audit gate
```xml
<NuGetAudit>true</NuGetAudit>
<NuGetAuditMode>all</NuGetAuditMode>
<NuGetAuditLevel>low</NuGetAuditLevel>
<WarningsAsErrors>$(WarningsAsErrors);NU1903;NU1904</WarningsAsErrors>
```
Every restore audits direct **and** transitive packages (`all` is already the default from `net10.0`; it is stated so it holds on older targets) and reports every severity (`low`). With `TreatWarningsAsErrors` on, **every reported advisory fails the build** — `NU1901` to `NU1904` alike; the explicit `NU1903;NU1904` only pins the two that must stay errors should the blanket setting ever go. The fix is a version bump, or an override of the transitive package in CPM. An advisory analyzed and judged not to apply is excluded with a `NuGetAuditSuppress` item naming its advisory URL — the last resort, and the only sanctioned one; never `NoWarn`.
## global.json
At the root, selecting the test runner — `{ "test": { "runner": "Microsoft.Testing.Platform" } }`. xUnit v3 defaults to VSTest under `dotnet test`, which would need `Microsoft.NET.Test.Sdk`; the test projects carry the MTP runner instead, so without this file `dotnet test` finds nothing (see `testing-dotnet`). Pin an SDK there only with a reason.
## Feeds
- **Every repo carries a `nuget.config` at its root**, and it always starts from the same base: `<clear />`, then `nuget.org` mapped to everything:
```xml
<configuration>
<packageSources>
<clear />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
</packageSources>
<packageSourceMapping>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
</packageSourceMapping>
</configuration>
```
`<clear />` drops every source inherited from the user-level and machine configs, so the repo restores the same everywhere, and with Central Package Management a second inherited source would otherwise raise `NU1507` — an error under the gates. A repo that consumes a private feed **extends** the base: one more `<add>`, and its own `packageSource` mapping its package prefix (`<Org>.*`), so a package can only come from the feed it belongs to.
- **It holds no credentials.** A developer's live in the user-level NuGet config; CI's come from a read-only token in an organization secret, passed as `NuGetPackageSourceCredentials_<FeedName>`.
- `nuget.config`, `appsettings*.json` and user secrets are never read or rewritten by tooling: hand changes to them to the user.
- Right after a package is published, a restore that can't find it is usually the HTTP cache — restore with `--no-http-cache` before suspecting the feed.