Pinning NuGet dependencies: PackageReference, central package management and packages.lock.json

Goal

Every restore of an application produces the same package closure on every machine and in CI, and any change in dependencies shows up as a reviewable diff.

Prerequisites

SDK-style projects using PackageReference rather than packages.config, one repository root, and a CI job that runs dotnet restore as its own step.

Steps

1. Understand the rules the dependency-resolution documentation lists: lowest applicable version (a reference to 4.0.0 means at least 4.0.0, and NuGet picks the lowest version that satisfies all constraints), direct-dependency-wins, and cousin dependencies. Floating versions such as 4.* opt into the newest match on every restore.
2. Move versions to one place: create Directory.Packages.props at the repository root with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> and one <PackageVersion Include="..." Version="..." /> per package; project files keep <PackageReference Include="..." /> without a version. The documentation states that only the nearest Directory.Packages.props is imported automatically, so keep a single one unless you import the parent explicitly.
3. Enable the lock file: set <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile> (in Directory.Build.props for all projects) and run dotnet restore; NuGet writes packages.lock.json at each project root listing the full closure, transitive packages included.
4. Commit the lock file of every application or executable at the start of a dependency chain. For a library project that other projects in the repository depend on, the documentation says not to check the lock file in: the consuming project's restore does not use it (the documentation adds that keeping it does no harm).
5. Restore in CI with dotnet restore --locked-mode (or RestoreLockedMode=true): restore then fails instead of silently regenerating the lock file when the declared dependencies changed without an updated lock.
6. To upgrade: change the version in Directory.Packages.props, run dotnet restore without locked mode (NuGet detects the changed input and rewrites the lock file; --force-evaluate is only needed to move a floating version), review the lock diff, commit both files together.
7. Pin the SDK with global.json (the documentation names the rollForward policy disable): it warns that implicit PackageReference items added by the SDK change with the SDK version and cause locked-mode failures.

Expected result

A fresh clone restores identical versions; git diff on an upgrade shows exactly which packages changed, including transitive ones; a new transitive package cannot enter the build unnoticed.

Limits and test basis

Floating versions and locked mode work against each other; choose one. Several target frameworks produce several dependency sets in one lock file. Lock files do not replace package source pinning in nuget.config or signature verification. This is a documented procedure; no restore-time measurements are claimed.