Lock-file deterministic restore vs explicit version downgrade for NuGet rollback reproducibility

Comparing Rollback Strategies

Locked-mode restore provides a safer rollback signal than an explicit downgrade when your dependency graph contains floating versions or version ranges. While an explicit downgrade ensures the direct dependency returns to a known state, it does not guarantee that transitive dependencies (the dependencies of your dependencies) will resolve to the same versions used during the original stable build.

When Locked-Mode is Superior

Locked-mode restore is the safer choice when you need to verify that the entire resolved graph is identical across environments. It is particularly critical when:

• Transitive dependencies are not pinned and may have released breaking changes.
• You are recovering from a failure where the direct dependency version remained the same, but a transitive update caused the regression.
• CI/CD pipelines must fail immediately if the resolved graph deviates from the developer's committed state.

Policy: Applications vs. Libraries

The decision to use lock files depends on who consumes the output:

Project Type	Lock File Policy	Reasoning
Applications	Enable and Commit	Ensures environment parity. The application is the final consumer; consistency in production is the priority.
Libraries	Disable/Do Not Commit	Avoids restricting the consumer. Forcing specific transitive versions can cause version conflicts (dependency hell) for the end-user.

Central Package Management (CPM) Consistency

Central Package Management simplifies versioning by moving declarations to a Directory.Packages.props file, but it does not replace the restore mechanism. The consistency guarantees remain as follows:

• With Explicit Downgrade: CPM ensures all projects in the solution use the same direct version, but transitive resolution still follows standard NuGet rules (potentially allowing drift).
• With Lock Files: CPM manages the input (direct versions), while the lock file captures the output (the full resolved graph). This combination provides the highest level of reproducibility.

Verification Steps

To implement and verify a locked-mode rollback in an SDK-style project:

1. Enable lock files in the .csproj:

   <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>

2. Run a restore to generate packages.lock.json and commit it to version control.
3. Verify the rollback in CI or a clean environment using:

   dotnet restore --locked-mode

Note: If --locked-mode is not used, the lock file is advisory and will not fail the build on mismatch.

Diagnostic Detail Needed: Are you using floating versions (e.g., 1.0.*) or specific version ranges in your PackageReference declarations?