csharp-cpm-migration

Skill: C# Central Package Management Migration

When to use: Migrating a multi-project .NET solution from per-csproj <PackageReference Version="..."> to a single Directory.Packages.props so future package bumps are one-line edits.

Steps

1. Inventory. From repo root: find . -name "*.csproj" -not -path "*/bin/*" -not -path "*/obj/*" then cat each one. Build a table of every distinct (PackageId, Version) pair and which projects use it.

2. Resolve drift. For any package referenced at multiple versions, pick the higher one (or the version actually being tested in CI). Surface these explicitly in the commit message — CPM consolidation is the moment to fix drift, not hide it.

3. Create Directory.Packages.props at the repo root (sibling of the .sln/.slnx):

   <Project>
     <PropertyGroup>
       <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
       <!-- Add only if any project pins a floating version like 17.* or 10.*-* -->
       <CentralPackageFloatingVersionsEnabled>true</CentralPackageFloatingVersionsEnabled>
     </PropertyGroup>
     <ItemGroup>
       <PackageVersion Include="PackageId" Version="x.y.z" />
       <!-- ... one entry per distinct package ... -->
     </ItemGroup>
   </Project>
   

   MSBuild auto-imports any Directory.Packages.props from each project up to the root — no <Import> needed.

4. Strip Version= from every PackageReference in every csproj. Keep Include= and any sibling attributes (PrivateAssets, OutputItemType, IncludeAssets, etc.). Example:

   • Before: <PackageReference Include="xunit" Version="2.*" />
   • After: <PackageReference Include="xunit" />

5. Include analyzer/source-generator projects too. netstandard2.0 source generator csprojs (e.g. with Microsoft.CodeAnalysis.CSharp) participate in CPM the same way. Don't skip them.

6. Restore. dotnet restore. Common failures and fixes:

   • NU1011 — "PackageVersion items cannot specify a floating version." → Add <CentralPackageFloatingVersionsEnabled>true</CentralPackageFloatingVersionsEnabled> to Directory.Packages.props. Alternative: pin to a concrete version, but that loses the original intent.
   • NU1008 — "Projects that use central package version management should not define the version on the PackageReference items." → A Version= attribute slipped through. Re-grep PackageReference.*Version= across all csprojs.
   • NU1507 — "There are N package sources defined… please map your package sources." → Pre-existing multi-source NuGet.config config that CPM now warns about. Out of scope for the migration commit; flag as follow-up. Fix later by adding <packageSourceMapping> to NuGet.config.