skip to content

In NuGet's Central Package Management, how would you move the 25 projects of an accounting suite onto one Directory.Packages.props, and which errors catch leftovers?

level: middleimportance: must knowfreq 55%

answer

  1. one file at the repository root
  2. ManagePackageVersionsCentrally plus PackageVersion items
  3. PackageReference keeps Include, loses Version
  4. NU1008 version left, NU1010 version missing
  5. only the nearest props file is imported

basics

~20 s

Add a Directory.Packages.props at the repository root with ManagePackageVersionsCentrally set to true and one PackageVersion per package, then strip Version from every PackageReference. Restore raises NU1008 for a leftover Version and NU1010 for a reference without a PackageVersion.

solid answer

~40 s

Central Package Management moves versions out of the projects. You create `Directory.Packages.props` at the repo root, set `ManagePackageVersionsCentrally` to `true`, and declare `<PackageVersion Include="..." Version="..." />` for each package; each `.csproj` keeps `<PackageReference Include="..." />` with **no** `Version`. Restore then enforces the contract: **NU1008** if a `PackageReference` still carries a version, **NU1010** if a reference has no matching `PackageVersion`, **NU1009** if you version an SDK-implicit package, and **NU1011** for a floating `PackageVersion`. MSBuild imports only the **nearest** `Directory.Packages.props` above a project, so a nested one must import its parent explicitly. Once onboarded, `dotnet package add` writes the version-less reference into the project and the `PackageVersion` into the props file.

code

xml · 10 lines
xml
<!-- Ledger.Payroll/Ledger.Payroll.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore" />
    <PackageReference Include="Serilog" />
  </ItemGroup>
</Project>

go deeper

for a junior

Know that versions move into Directory.Packages.props as PackageVersion items and that project files keep PackageReference without a Version.

for a middle

Explain the nearest-file import rule, the ManagePackageVersionsCentrally switch, and what NU1008, NU1010, NU1009 and NU1011 each catch during a migration.

for a senior

Plan the migration of a large solution: choosing one version per package, per-framework conditions, nested props files, and how dotnet package add now edits the central file.

for a principal

Weigh central versions as a governance tool: who approves upgrades, how exceptions are allowed, and how the repository avoids becoming stuck on old versions.

## Why centralise An accounting suite of 25 projects — ledger, payables, receivables, payroll, tax reports, their tests — tends to grow 25 copies of `Version="..."` for the same packages. Each upgrade touches many files, some get missed, and different projects resolve different versions. **Central Package Management (CPM)** declares each version once and makes restore reject anything that bypasses it. NuGet marked CPM production-ready in 6.4; it applies to every PackageReference-based project. ## The two halves of the setup The central file, at the repository root: ```xml <Project> <PropertyGroup> <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> </PropertyGroup> <ItemGroup> <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="10.0.12" /> <PackageVersion Include="Serilog" Version="4.4.0" /> </ItemGroup> </Project> ``` Each project then references packages without versions: `<PackageReference Include="Serilog" />`. A project only gets the packages it references; a `PackageVersion` is a version declaration, not a reference. Two details from `NuGet.props` and `NuGet.targets` matter: - The file is located with `GetDirectoryNameOfFileAbove`, so a project imports **only the nearest** `Directory.Packages.props` above it. A nested file for one sub-solution must import its parent itself (with `GetPathOfFileAbove`) and can then adjust entries with `<PackageVersion Update="..." />`. - CPM is on only when `ManagePackageVersionsCentrally` is `true` **and** the file was imported. The file's mere presence does not enable it, and a single project can opt out by setting the property to `false`. ## Migrating the 25 projects 1. Collect every `PackageReference` and its version across the solution and choose one version per package (usually the highest in use). 2. Write those as `PackageVersion` items in the root `Directory.Packages.props` with `ManagePackageVersionsCentrally` set. 3. Delete the `Version` attribute (or `<Version>` child) from every `PackageReference`. 4. Restore and work through the errors below until it is clean. 5. Where a multi-targeting project needs different versions per framework, put a `Condition` on `$(TargetFramework)` in the `PackageVersion` items. ## The errors that police it | Code | Trigger | |---|---| | NU1008 | a `PackageReference` still defines `Version` | | NU1010 | a `PackageReference` has no matching `PackageVersion` | | NU1009 | a `PackageVersion` was declared for an SDK-implicit package | | NU1011 | a `PackageVersion` uses a floating version such as `1.*` | | NU1507 | more than one package source and no package source mapping | Floating central versions are blocked unless `CentralPackageFloatingVersionsEnabled` is `true`, because CPM's point is that every upgrade is a reviewed commit. NU1507 is a warning; its remedy, source mapping, lives in `nuget.config`. ## Per-framework and per-project differences A multi-targeting library in the suite — say a shared `Ledger.Contracts` built for `netstandard2.0` and `net10.0` — may need an older version of a package for the older target. `PackageVersion` items accept MSBuild conditions, so the props file can carry two entries for one id, each with a `Condition` on `'$(TargetFramework)'`. A project that must leave CPM entirely, such as a sample kept deliberately standalone, sets `ManagePackageVersionsCentrally` to `false` in its own file and goes back to versioned references. Anything finer — one project on one different version — is a `VersionOverride`, covered separately from the basic setup. ## What CPM does not do CPM is often oversold, so it helps to say what it leaves alone: - It versions **direct** references only. A transitive package still resolves by the lowest-applicable rule unless transitive pinning is switched on. - It does not freeze the resolved graph; a floor in the props file is still a floor. Repeatable graphs are the job of lock files. - It does not choose sources; with several feeds, NU1507 nudges you toward package source mapping in `nuget.config`. - It does not add packages to projects; `GlobalPackageReference` is the separate feature for packages every project needs. ## Day-to-day commands - `dotnet package add Serilog --project Ledger.Payroll/Ledger.Payroll.csproj` adds `<PackageReference Include="Serilog" />` to the project and, if no `PackageVersion` exists, adds one with the latest stable version. - If the `PackageVersion` already exists, running the command without `--version` reuses it; running it **with** `--version` rewrites the central entry, which changes the version for every project that references the package. - Since NuGet 7.6 (SDK 10.0.300), `--no-restore` under CPM also writes the version-less reference instead of producing NU1008. The effect is the one the suite wanted: an EF Core upgrade is a one-line change in one file, and a project that tries to sneak in its own version fails restore.

  • A developer copies a csproj with Version="4.4.0" on a PackageReference into the CPM repo. What happens?
    Restore fails with NU1008: projects using Central Package Management may not define a version on `PackageReference`. The fix is to delete the attribute and, if the package is new to the repo, add a `PackageVersion` for it in `Directory.Packages.props`; one project that truly needs another version uses `VersionOverride` instead.
  • Why does a Directory.Packages.props in a sub-folder seem to lose all the root versions?
    NuGet.props imports only the first `Directory.Packages.props` found walking up from the project, so the nested file replaces the root one for that subtree. It must `Import` the parent with `GetPathOfFileAbove` and then use `PackageVersion Update` for the entries it changes.
  • Does putting a package in Directory.Packages.props add it to every project?
    No. A `PackageVersion` only supplies a version; a project gets the package when it has a `PackageReference`. To add a package to every project you use `GlobalPackageReference`, which is meant for build-only packages such as versioning tools and analyzers.

  • Under CPM a PackageReference may keep its Version as long as it matches.
  • Every Directory.Packages.props up the folder tree is merged automatically.
  • A PackageVersion item adds the package to every project in the repository.
  • Dropping a Directory.Packages.props into the repo turns CPM on by itself.
  • dotnet package add --version under CPM changes only the current project.

Assumes NuGet 7 as shipped in the .NET 10.0.400 SDK (7.9); CPM left preview in NuGet 6.4, and the --no-restore fix for dotnet package add under CPM landed in NuGet 7.6 (SDK 10.0.300).