Skip to content

docs: recommend pinning SDK version when using NuGet package lock files #54846

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
+17 −1
Draft

docs: recommend pinning SDK version when using NuGet package lock files #54846

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
158e839
Initial plan
Copilot Jul 21, 2026
32c4192
Add SDK pinning recommendation to package lock files docs
Copilot Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion docs/core/install/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Upgrade to a new .NET version
description: Learn how to upgrade an app to a new .NET version. Upgrade .NET when the current version goes out of support or when you want to use new features of .NET. Control versions of SDK, analyzers, and packages for predictable builds.
ms.date: 04/23/2026
ms.date: 07/21/2026
ai-usage: ai-assisted
---

Expand Down Expand Up @@ -141,6 +141,22 @@ To ensure builds fail if the lock file is out of date:

After enabling lock files, run `dotnet restore` to generate the *packages.lock.json* file. Commit this file to source control.

> [!IMPORTANT]
> When you use package lock files, also pin the SDK version in a *global.json* file with `rollForward` set to `disable`. This keeps the SDK version and dependency graph in lockstep, preventing the lock file from changing unexpectedly when the SDK updates.

Create a *global.json* file at the solution root with the exact SDK version and no roll-forward:

```json
{
"sdk": {
"version": "9.0.100",
"rollForward": "disable"
}
}
```

For more information, see [Control SDK version with global.json](#control-sdk-version-with-globaljson). For related tracking issues, see <https://github.com/dotnet/aspnetcore/issues/65061> and <https://github.com/dotnet/sdk/issues/48795>.

#### Central package management

Central package management (CPM) allows you to manage package versions in a single location for all projects in a solution. This approach simplifies version management and ensures consistency across projects.
Expand Down