Skip to content

Commit 8561836

Browse files
CopilotCopilot
authored
Expand upgrade documentation with version pinning and controlled upgrade guidance (#49510)
1 parent a416869 commit 8561836

File tree

2 files changed

+175
-10
lines changed

2 files changed

+175
-10
lines changed

‎docs/core/install/upgrade.md‎

Lines changed: 167 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
22
title: Upgrade to a new .NET version
3-
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.
4-
ms.date: 11/11/2024
3+
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.
4+
ms.date: 10/28/2025
5+
ai-usage: ai-assisted
56
---
67

78
# Upgrade to a new .NET version
@@ -51,6 +52,165 @@ More resources:
5152
- [Migrate an ASP.NET Core app](/aspnet/core/migration/)
5253
- [Upgrade .NET MAUI from .NET 7 to .NET 8](https://github.com/dotnet/maui/wiki/Upgrading-.NET-MAUI-from-.NET-7-to-.NET-8)
5354

55+
## Version pinning
56+
57+
When you upgrade development tools like the .NET SDK, Visual Studio, or other components, you might encounter new behaviors, analyzer warnings, or breaking changes that affect your build process. By pinning to a version, you can upgrade your development environment while maintaining control over when specific components are updated in your projects.
58+
59+
Version pinning provides several benefits:
60+
61+
- **Predictable builds**: Ensures consistent build results across different machines and CI/CD environments.
62+
- **Gradual adoption**: Allows you to adopt new features incrementally rather than all at once.
63+
- **Avoid unexpected changes**: Prevents new analyzer rules, SDK behaviors, or package versions from causing build failures.
64+
- **Team coordination**: Enables teams to upgrade together at a planned time rather than individually when tools update.
65+
- **Debugging and troubleshooting**: Makes it easier to isolate issues when you control which versions changed.
66+
67+
The following sections describe various mechanisms for controlling versions of different components in your .NET projects:
68+
69+
- [Control SDK version with global.json](#control-sdk-version-with-globaljson)
70+
- [Control analyzer behavior](#control-analyzer-behavior)
71+
- [Control NuGet package versions](#control-nuget-package-versions)
72+
- [Control MSBuild version](#control-msbuild-version)
73+
74+
### Control SDK version with global.json
75+
76+
You can pin the .NET SDK version for a project or solution by using a *global.json* file. This file specifies which SDK version to use when running .NET CLI commands and is independent of the runtime version your project targets.
77+
78+
Create a *global.json* file in your solution root directory:
79+
80+
```dotnetcli
81+
dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature
82+
```
83+
84+
This command creates the following *global.json* file that pins the SDK to version 9.0.100 or any later patch or feature band within the 9.0 major version:
85+
86+
```json
87+
{
88+
"sdk": {
89+
"version": "9.0.100",
90+
"rollForward": "latestFeature"
91+
}
92+
}
93+
```
94+
95+
The `rollForward` policy controls how the SDK version is selected when the exact version isn't available. This configuration ensures that when you upgrade Visual Studio or install a new SDK, your project continues to use SDK 9.0.x until you explicitly update the *global.json* file.
96+
97+
For more information, see [global.json overview](../tools/global-json.md).
98+
99+
### Control analyzer behavior
100+
101+
Code analyzers can introduce new warnings or change behavior between versions. You can control analyzer versions to maintain consistent builds by using the [`AnalysisLevel` property](../project-sdk/msbuild-props.md#analysislevel). This property allows you to lock to a specific version of analyzer rules, preventing new rules from being introduced when you upgrade the SDK.
102+
103+
```xml
104+
<PropertyGroup>
105+
<AnalysisLevel>9.0</AnalysisLevel>
106+
</PropertyGroup>
107+
```
108+
109+
When set to `9.0`, only the analyzer rules that shipped with .NET 9 are enabled, even if you're using the .NET 10 SDK. This prevents new .NET 10 analyzer rules from affecting your build until you're ready to address them.
110+
111+
For more information, see [AnalysisLevel](../project-sdk/msbuild-props.md#analysislevel).
112+
113+
### Control NuGet package versions
114+
115+
By managing package versions consistently across projects, you can prevent unexpected updates and maintain reliable builds.
116+
117+
- [Package lock files](#package-lock-files)
118+
- [Central package management](#central-package-management)
119+
- [Package source mapping](#package-source-mapping)
120+
121+
#### Package lock files
122+
123+
Package lock files ensure that package restore operations use the exact same package versions across different environments. The lock file (`packages.lock.json`) records the exact versions of all packages and their dependencies.
124+
125+
Enable lock files in your project file:
126+
127+
```xml
128+
<PropertyGroup>
129+
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
130+
</PropertyGroup>
131+
```
132+
133+
To ensure builds fail if the lock file is out of date:
134+
135+
```xml
136+
<PropertyGroup>
137+
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
138+
<RestoreLockedMode>true</RestoreLockedMode>
139+
</PropertyGroup>
140+
```
141+
142+
After enabling lock files, run `dotnet restore` to generate the *packages.lock.json* file. Commit this file to source control.
143+
144+
#### Central package management
145+
146+
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.
147+
148+
Create a *Directory.Packages.props* file in your solution root:
149+
150+
```xml
151+
<Project>
152+
<PropertyGroup>
153+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
154+
</PropertyGroup>
155+
156+
<ItemGroup>
157+
<PackageVersion Include="Azure.Identity" Version="1.17.0" />
158+
<PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
159+
</ItemGroup>
160+
</Project>
161+
```
162+
163+
In your project files, reference packages without specifying a version:
164+
165+
```xml
166+
<ItemGroup>
167+
<PackageReference Include="Azure.Identity" />
168+
<PackageReference Include="Microsoft.Extensions.AI" />
169+
</ItemGroup>
170+
```
171+
172+
#### Package source mapping
173+
174+
Package source mapping allows you to control which NuGet feeds are used for specific packages, improving security and reliability.
175+
176+
Configure source mapping in your *nuget.config* file:
177+
178+
```xml
179+
<configuration>
180+
<packageSources>
181+
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
182+
<add key="contoso" value="https://contoso.com/packages/" />
183+
</packageSources>
184+
185+
<packageSourceMapping>
186+
<packageSource key="nuget.org">
187+
<package pattern="*" />
188+
</packageSource>
189+
<packageSource key="contoso">
190+
<package pattern="Contoso.*" />
191+
</packageSource>
192+
</packageSourceMapping>
193+
</configuration>
194+
```
195+
196+
This configuration ensures that all packages starting with `Contoso.` are only restored from the `contoso` feed, while other packages come from `nuget.org`.
197+
198+
For more information, see [NuGet package restore](../tools/dotnet-restore.md).
199+
200+
### Control MSBuild version
201+
202+
Visual Studio supports side-by-side installation of multiple versions. For example, you can install Visual Studio 2026 and Visual Studio 2022 on the same machine. Each Visual Studio version includes a corresponding .NET SDK. When you update Visual Studio, the included SDK version is updated as well. However, you can continue using older SDK versions by installing them separately from the [.NET download page](https://dotnet.microsoft.com/download).
203+
204+
MSBuild versions correspond to Visual Studio versions. For example, Visual Studio 2022 version 17.8 includes MSBuild 17.8. The .NET SDK also includes MSBuild. When you use `dotnet build`, you're using the MSBuild version included with the SDK specified by *global.json* or the latest installed SDK.
205+
206+
To use a specific MSBuild version:
207+
208+
- Use `dotnet build` with a pinned SDK version in *global.json*.
209+
- Launch the appropriate Visual Studio Developer Command Prompt, which sets up the environment for that Visual Studio version's MSBuild.
210+
- Directly invoke MSBuild from a specific Visual Studio installation (for example, `"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe"`).
211+
212+
For more information, see [.NET SDK, MSBuild, and Visual Studio versioning](../porting/versioning-sdk-msbuild-vs.md).
213+
54214
## Update continuous integration (CI)
55215

56216
CI pipelines follow a similar update process as project files and Dockerfiles. Typically, you can update [CI pipelines](https://github.com/actions/setup-dotnet) by changing only version values.
@@ -68,3 +228,8 @@ FROM mcr.microsoft.com/dotnet/aspnet:9.0
68228
```
69229

70230
In a cloud service like [Azure App Service](/azure/app-service/quickstart-dotnetcore), a configuration change is needed.
231+
232+
## See also
233+
234+
- [Breaking changes in .NET 10](../compatibility/10.0.md)
235+
- [Migrate an ASP.NET Core app](/aspnet/core/migration/)

‎docs/fundamentals/code-analysis/configuration-options.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -78,14 +78,14 @@ Rule-specific options can be applied to a single rule, a set of rules, or all ru
7878

7979
The following table shows the different rule severities that you can configure for all analyzer rules, including [code quality](quality-rules/index.md) and [code style](style-rules/index.md) rules.
8080

81-
| Severity configuration value | Build-time behavior |
82-
|-|-|
83-
| `error` | Violations appear as build *errors* and cause builds to fail.|
84-
| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). |
85-
| `suggestion` | Violations appear as build *messages* and as suggestions in the Visual Studio IDE. (In Visual Studio, suggestions appear as three gray dots under the first two characters.) |
86-
| `silent` | Violations aren't visible to the user.<br/><br/>However, for code-style rules, Visual Studio code-generation features still generate code in this style. These rules also participate in cleanup and appear in the **Quick Actions and Refactorings** menu in Visual Studio. |
87-
| `none` | Rule is suppressed completely.<br/><br/>However, for code-style rules, Visual Studio code-generation features still generate code in this style. |
88-
| `default` | The default severity of the rule is used. The default severities for each .NET release are listed in the [roslyn-analyzers repo](https://github.com/dotnet/roslyn-analyzers/blob/main/src/NetAnalyzers/Core/AnalyzerReleases.Shipped.md). In that table, "Disabled" corresponds to `none`, "Hidden" corresponds to `silent`, and "Info" corresponds to `suggestion`. |
81+
| Severity configuration value | Build-time behavior |
82+
|------------------------------|---------------------------------------------------------------|
83+
| `error` | Violations appear as build *errors* and cause builds to fail. |
84+
| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). |
85+
| `suggestion` | Violations appear as build *messages* and as suggestions in the Visual Studio IDE. (In Visual Studio, suggestions appear as three gray dots under the first two characters.) |
86+
| `silent` | Violations aren't visible to the user.<br/><br/>However, for code-style rules, Visual Studio code-generation features still generate code in this style. These rules also participate in cleanup and appear in the **Quick Actions and Refactorings** menu in Visual Studio. |
87+
| `none` | Rule is suppressed completely.<br/><br/>However, for code-style rules, Visual Studio code-generation features still generate code in this style. |
88+
| `default` | The default severity of the rule is used. The default severities for each .NET release are listed in the [roslyn-analyzers repo](https://github.com/dotnet/roslyn-analyzers/blob/main/src/NetAnalyzers/Core/AnalyzerReleases.Shipped.md). In that table, "Disabled" corresponds to `none`, "Hidden" corresponds to `silent`, and "Info" corresponds to `suggestion`. |
8989

9090
#### Scope
9191

0 commit comments

Comments
 (0)