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?
answer
- one file at the repository root
- ManagePackageVersionsCentrally plus PackageVersion items
- PackageReference keeps Include, loses Version
- NU1008 version left, NU1010 version missing
- only the nearest props file is imported
basics
~20 sAdd 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 sCentral 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<!-- 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
Know that versions move into Directory.Packages.props as PackageVersion items and that project files keep PackageReference without a Version.
Explain the nearest-file import rule, the ManagePackageVersionsCentrally switch, and what NU1008, NU1010, NU1009 and NU1011 each catch during a migration.
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.
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).