NuGet/Home

Lock file docs should mention it's recommended to use `global.json` with `rollForward = disable` when using lock files

Open

#14867 opened on Apr 22, 2026

View on GitHub
 (1 comment) (0 reactions) (0 assignees)HTML (1,459 stars) (292 forks)batch import
Priority:3Type:Docshelp wanted

Description

Docs Page URL

https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#locking-dependencies

Description of the Issue

See comment from Microsoft(Chet) here https://github.com/dotnet/sdk/issues/48795#issuecomment-3001803076

Our current recommendation for users that use lock files is to also lock their SDK versions via global.json with no rollforward, so they(sic) their entire toolchain stays in lockstep.

Discovery of this recommendation is currently hard

Suggested Fix

Add some version of: Our current recommendation for users that use lock files is to also lock their SDK versions via global.json with no rollforward, so they their entire toolchain stays in lockstep.

Ideally linking to an issue to track for when that recommendation changes or at least the specific issues which most users run into which require pinning the SDK in relation to lock-files https://github.com/dotnet/aspnetcore/issues/64897 https://github.com/dotnet/sdk/issues/48795

Ideally the blog post https://devblogs.microsoft.com/dotnet/enable-repeatable-package-restores-using-a-lock-file/ is also updated

Opened related global.json docs issue here https://github.com/dotnet/docs/issues/53347

Additional Context

https://github.com/dotnet/sdk/issues/48795 https://github.com/dotnet/aspnetcore/issues/65061 https://github.com/microsoft/azure-pipelines-tasks/issues/22040

Contributor guide

Tech stack
csharp
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
NuGet lock filesglobal.json configuration
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85
Research direction
Review the current NuGet lock files documentation at https://learn.microsoft.com/en us/nuget/consume packages/package references in project files#locking dependencies. Read the comment from Microsoft (Chet) at https://github.com/dotnet/sdk/issues/48795#issuecomment 3001803076 for context. Check linked issues for specific examples of problems when SDK version is not pinned. Then add the recommended sentence and links to the documentation.