From 3b2ae00ce71953511a181d5732296f2d1cfe298b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 18:11:56 +0000 Subject: [PATCH 1/4] Initial plan From 3c6749aa168558fc51494b5142ba0c4e0a97050a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 18:19:37 +0000 Subject: [PATCH 2/4] Expand upgrade documentation with version pinning guidance Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/install/upgrade.md | 282 ++++++++++++++++++++++++++++++++++- 1 file changed, 281 insertions(+), 1 deletion(-) diff --git a/docs/core/install/upgrade.md b/docs/core/install/upgrade.md index 8fa3fee613b96..7adecb7f7f8b9 100644 --- a/docs/core/install/upgrade.md +++ b/docs/core/install/upgrade.md @@ -1,7 +1,8 @@ --- 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. +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: 11/11/2024 +ai-usage: ai-assisted --- # Upgrade to a new .NET version @@ -14,6 +15,22 @@ Common reasons to upgrade to a new .NET version: - The new version supports a new operating system - The new version has an important API, performance, or security feature +## Controlled upgrades and version pinning + +When upgrading 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. Version pinning allows you to upgrade your development environment while maintaining control over when specific components are updated in your projects. + +### Why pinning matters + +Pinning versions provides several benefits: + +- **Predictable builds**: Ensures consistent build results across different machines and CI/CD environments. +- **Gradual adoption**: Allows you to adopt new features incrementally rather than all at once. +- **Avoid unexpected changes**: Prevents new analyzer rules, SDK behaviors, or package versions from causing build failures. +- **Team coordination**: Enables teams to upgrade together at a planned time rather than individually when tools update. +- **Debugging and troubleshooting**: Makes it easier to isolate issues when you control which versions changed. + +The following sections describe various mechanisms for controlling versions of different components in your .NET projects. + ## Upgrade development environment To upgrade to a new .NET version, the .NET SDK is the primary component to install. It includes an updated .NET CLI, build system, and runtime version. @@ -51,6 +68,269 @@ More resources: - [Migrate an ASP.NET Core app](/aspnet/core/migration/) - [Upgrade .NET MAUI from .NET 7 to .NET 8](https://github.com/dotnet/maui/wiki/Upgrading-.NET-MAUI-from-.NET-7-to-.NET-8) +## Control SDK version with global.json + +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. + +Create a *global.json* file in your solution root directory: + +```dotnetcli +dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature +``` + +This example pins the SDK to version 9.0.100 or any later patch or feature band within the 9.0 major version. The `rollForward` policy controls how the SDK version is selected when the exact version isn't available. + +Common roll-forward strategies: + +- **`disable`**: Requires the exact SDK version specified. +- **`patch`**: Allows the latest patch version of the specified SDK. +- **`feature`**: Allows the latest feature band within the same major and minor version. +- **`latestFeature`**: Uses the highest feature band and patch within the same major and minor version (recommended for most scenarios). +- **`latestMinor`**: Allows any minor version within the same major version. + +Example *global.json* file: + +```json +{ + "sdk": { + "version": "9.0.100", + "rollForward": "latestFeature" + } +} +``` + +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. + +For more information, see [global.json overview](../tools/global-json.md). + +## Control analyzer behavior + +Code analyzers can introduce new warnings or change behavior between versions. You can control analyzer versions and which rules are enabled to maintain consistent builds. + +### AnalysisLevel + +The `AnalysisLevel` property controls which code quality rules are enabled. This property allows you to lock to a specific version of analyzer rules, preventing new rules from being introduced when you upgrade the SDK. + +```xml + + 8.0 + +``` + +When set to `8.0`, only the analyzer rules that shipped with .NET 8 are enabled, even if you're using the .NET 9 SDK. This prevents new .NET 9 analyzer rules from affecting your build until you're ready to address them. + +Available values: + +- **`latest`**: Uses all analyzer rules from the SDK you're building with (default). +- **`latest-all`**: Uses all analyzer rules, including those in preview. +- **`latest-recommended`**: Uses only recommended analyzer rules. +- **Specific version** (for example, `8.0`, `9.0`): Uses rules from that .NET version. + +### AnalysisMode + +The `AnalysisMode` property determines how aggressive the analyzer rules should be: + +```xml + + Default + +``` + +Available values: + +- **`Default`**: Default set of rules. +- **`None`**: Disables most analyzer rules. +- **`Minimum`**: Enables only the most critical rules. +- **`Recommended`**: Enables recommended rules (default in .NET 8 and later). +- **`All`**: Enables all available analyzer rules. + +You can also control analysis mode by category: + +```xml + + All + Recommended + +``` + +For more information, see [Code analysis configuration options](../../fundamentals/code-analysis/configuration-options.md). + +## Control NuGet package versions + +Managing package versions consistently across projects and preventing unexpected updates is critical for reliable builds. + +### Package lock files + +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. + +Enable lock files in your project file: + +```xml + + true + +``` + +To ensure builds fail if the lock file is out of date: + +```xml + + true + true + +``` + +After enabling lock files, run `dotnet restore` to generate the *packages.lock.json* file. Commit this file to source control. + +### 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. + +Create a *Directory.Packages.props* file in your solution root: + +```xml + + + true + + + + + + + +``` + +In your project files, reference packages without specifying versions: + +```xml + + + + +``` + +The versions are managed centrally in *Directory.Packages.props*, making it easier to update all projects at once. + +### Package Source Mapping + +Package Source Mapping allows you to control which NuGet feeds are used for specific packages, improving security and reliability. + +Configure source mapping in your *nuget.config* file: + +```xml + + + + + + + + + + + + + + + +``` + +This configuration ensures that all packages starting with `Contoso.` are only restored from the `contoso` feed, while other packages come from `nuget.org`. + +For more information, see [NuGet package restore](../tools/dotnet-restore.md). + +## Manage Visual Studio and MSBuild versions + +### Visual Studio side-by-side installation + +Visual Studio supports side-by-side installation of multiple versions. You can install Visual Studio 2022 and Visual Studio 2019 on the same machine, or multiple releases of Visual Studio 2022 (for example, 17.8 and 17.12). + +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). + +Key points: + +- Visual Studio updates don't affect separately installed .NET SDKs. +- Use *global.json* to control which SDK version is used, regardless of the Visual Studio version. +- Each Visual Studio instance can have different settings and extensions. + +### MSBuild versioning + +MSBuild versions correspond to Visual Studio versions: + +- Visual Studio 2022 version 17.8 includes MSBuild 17.8 +- Visual Studio 2022 version 17.12 includes MSBuild 17.12 + +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. + +To specify a specific MSBuild version: + +- Use `dotnet build` with a pinned SDK version in *global.json*. +- Launch the appropriate Visual Studio Developer Command Prompt, which sets up the environment for that Visual Studio version's MSBuild. +- Directly invoke MSBuild from a specific Visual Studio installation (for example, `"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe"`). + +For more information, see [.NET SDK, MSBuild, and Visual Studio versioning](../porting/versioning-sdk-msbuild-vs.md). + +## Upgrade readiness checklist + +Before upgrading to a new .NET version or development environment, use this checklist to ensure a smooth transition: + +### Pre-upgrade assessment + +- [ ] Review the [breaking changes](../compatibility/9.0.md) for the new .NET version. +- [ ] Check if your NuGet packages support the new .NET version. +- [ ] Verify that any third-party tools and libraries are compatible. +- [ ] Review the [.NET support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) for the versions you're using and upgrading to. + +### Version pinning setup + +- [ ] Create or update *global.json* to pin the SDK version. +- [ ] Set `AnalysisLevel` to lock analyzer rules to the current version. +- [ ] Enable package lock files (`RestorePackagesWithLockFile`) for consistent package versions. +- [ ] Consider setting up Central Package Management if managing multiple projects. +- [ ] Configure package source mapping if using multiple NuGet feeds. + +### Development environment + +- [ ] Install the new .NET SDK version. +- [ ] Update Visual Studio (if applicable) or install it side-by-side with existing versions. +- [ ] Update IDE extensions and tools. +- [ ] Verify that your CI/CD pipeline can use the new SDK version. + +### Code changes + +- [ ] Update `TargetFramework` (or `TargetFrameworks`) in project files. +- [ ] Run `dotnet restore` to restore packages with the new framework. +- [ ] Build the project and address any errors or warnings. +- [ ] Run tests to ensure functionality is preserved. +- [ ] Update code to address any breaking changes. + +### Gradual rollout + +- [ ] Update non-critical projects first to identify issues. +- [ ] Test in a non-production environment before deploying. +- [ ] Update *global.json* and `AnalysisLevel` to allow newer SDK and analyzer versions gradually. +- [ ] Review and address new analyzer warnings over time. +- [ ] Update package versions incrementally to manage risk. + +### CI/CD and deployment + +- [ ] Update CI/CD pipelines with the new SDK version. +- [ ] Update Docker base images if using containers. +- [ ] Verify that the hosting environment supports the new runtime version. +- [ ] Test the deployment process in a staging environment. + +## Workload-specific migration guides + +Different .NET workloads might have specific upgrade considerations: + +- **ASP.NET Core**: [Migrate from ASP.NET Core (version) to (version)](/aspnet/core/migration/) +- **Entity Framework Core**: [Upgrading from previous versions to EF Core (version)](/ef/core/what-is-new/ef-core-9.0/breaking-changes) +- **.NET MAUI**: [Upgrading .NET MAUI applications](https://github.com/dotnet/maui/wiki/Upgrading-.NET-MAUI-from-.NET-7-to-.NET-8) +- **Blazor**: Included in ASP.NET Core migration guides +- **Windows Forms and WPF**: [Upgrade a Windows desktop app to .NET](/dotnet/desktop/migration/) +- **.NET Upgrade Assistant**: [Overview of the .NET Upgrade Assistant](../porting/upgrade-assistant-overview.md) + ## Update continuous integration (CI) 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. From 08800bf12349bacaa6de92e09f706570af9559fe Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 28 Oct 2025 13:03:13 -0700 Subject: [PATCH 3/4] human edits --- docs/core/install/upgrade.md | 211 ++++-------------- .../code-analysis/configuration-options.md | 16 +- 2 files changed, 55 insertions(+), 172 deletions(-) diff --git a/docs/core/install/upgrade.md b/docs/core/install/upgrade.md index 7adecb7f7f8b9..bc58911523864 100644 --- a/docs/core/install/upgrade.md +++ b/docs/core/install/upgrade.md @@ -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: 11/11/2024 +ms.date: 10/28/2025 ai-usage: ai-assisted --- @@ -17,19 +17,7 @@ Common reasons to upgrade to a new .NET version: ## Controlled upgrades and version pinning -When upgrading 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. Version pinning allows you to upgrade your development environment while maintaining control over when specific components are updated in your projects. - -### Why pinning matters - -Pinning versions provides several benefits: - -- **Predictable builds**: Ensures consistent build results across different machines and CI/CD environments. -- **Gradual adoption**: Allows you to adopt new features incrementally rather than all at once. -- **Avoid unexpected changes**: Prevents new analyzer rules, SDK behaviors, or package versions from causing build failures. -- **Team coordination**: Enables teams to upgrade together at a planned time rather than individually when tools update. -- **Debugging and troubleshooting**: Makes it easier to isolate issues when you control which versions changed. - -The following sections describe various mechanisms for controlling versions of different components in your .NET projects. +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](#version-pinning), you can upgrade your development environment while maintaining control over when specific components are updated in your projects. ## Upgrade development environment @@ -68,7 +56,24 @@ More resources: - [Migrate an ASP.NET Core app](/aspnet/core/migration/) - [Upgrade .NET MAUI from .NET 7 to .NET 8](https://github.com/dotnet/maui/wiki/Upgrading-.NET-MAUI-from-.NET-7-to-.NET-8) -## Control SDK version with global.json +## Version pinning + +Version pinning provides several benefits: + +- **Predictable builds**: Ensures consistent build results across different machines and CI/CD environments. +- **Gradual adoption**: Allows you to adopt new features incrementally rather than all at once. +- **Avoid unexpected changes**: Prevents new analyzer rules, SDK behaviors, or package versions from causing build failures. +- **Team coordination**: Enables teams to upgrade together at a planned time rather than individually when tools update. +- **Debugging and troubleshooting**: Makes it easier to isolate issues when you control which versions changed. + +The following sections describe various mechanisms for controlling versions of different components in your .NET projects: + +- [Control SDK version with global.json](#control-sdk-version-with-globaljson) +- [Control analyzer behavior](#control-analyzer-behavior) +- [Control NuGet package versions](#control-nuget-package-versions) +- [Control MSBuild version](#control-msbuild-version) + +### Control SDK version with global.json 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. @@ -78,17 +83,7 @@ Create a *global.json* file in your solution root directory: dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature ``` -This example pins the SDK to version 9.0.100 or any later patch or feature band within the 9.0 major version. The `rollForward` policy controls how the SDK version is selected when the exact version isn't available. - -Common roll-forward strategies: - -- **`disable`**: Requires the exact SDK version specified. -- **`patch`**: Allows the latest patch version of the specified SDK. -- **`feature`**: Allows the latest feature band within the same major and minor version. -- **`latestFeature`**: Uses the highest feature band and patch within the same major and minor version (recommended for most scenarios). -- **`latestMinor`**: Allows any minor version within the same major version. - -Example *global.json* file: +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: ```json { @@ -99,67 +94,29 @@ Example *global.json* file: } ``` -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. +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. For more information, see [global.json overview](../tools/global-json.md). -## Control analyzer behavior - -Code analyzers can introduce new warnings or change behavior between versions. You can control analyzer versions and which rules are enabled to maintain consistent builds. +### Control analyzer behavior -### AnalysisLevel - -The `AnalysisLevel` property controls which code quality rules are enabled. This property allows you to lock to a specific version of analyzer rules, preventing new rules from being introduced when you upgrade the SDK. +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. ```xml - 8.0 + 9.0 ``` -When set to `8.0`, only the analyzer rules that shipped with .NET 8 are enabled, even if you're using the .NET 9 SDK. This prevents new .NET 9 analyzer rules from affecting your build until you're ready to address them. +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. -Available values: +For more information, see [AnalysisLevel](../project-sdk/msbuild-props.md#analysislevel). -- **`latest`**: Uses all analyzer rules from the SDK you're building with (default). -- **`latest-all`**: Uses all analyzer rules, including those in preview. -- **`latest-recommended`**: Uses only recommended analyzer rules. -- **Specific version** (for example, `8.0`, `9.0`): Uses rules from that .NET version. +### Control NuGet package versions -### AnalysisMode +By managing package versions consistently across projects, you can prevent unexpected updates and maintain reliable builds. -The `AnalysisMode` property determines how aggressive the analyzer rules should be: - -```xml - - Default - -``` - -Available values: - -- **`Default`**: Default set of rules. -- **`None`**: Disables most analyzer rules. -- **`Minimum`**: Enables only the most critical rules. -- **`Recommended`**: Enables recommended rules (default in .NET 8 and later). -- **`All`**: Enables all available analyzer rules. - -You can also control analysis mode by category: - -```xml - - All - Recommended - -``` - -For more information, see [Code analysis configuration options](../../fundamentals/code-analysis/configuration-options.md). - -## Control NuGet package versions - -Managing package versions consistently across projects and preventing unexpected updates is critical for reliable builds. - -### Package lock files +#### Package lock files 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. @@ -182,9 +139,9 @@ 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. -### Central Package Management +#### 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. +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. Create a *Directory.Packages.props* file in your solution root: @@ -195,8 +152,8 @@ Create a *Directory.Packages.props* file in your solution root: - - + + ``` @@ -205,16 +162,14 @@ In your project files, reference packages without specifying versions: ```xml - - + + ``` -The versions are managed centrally in *Directory.Packages.props*, making it easier to update all projects at once. - -### Package Source Mapping +#### Package source mapping -Package Source Mapping allows you to control which NuGet feeds are used for specific packages, improving security and reliability. +Package source mapping allows you to control which NuGet feeds are used for specific packages, improving security and reliability. Configure source mapping in your *nuget.config* file: @@ -240,30 +195,13 @@ This configuration ensures that all packages starting with `Contoso.` are only r For more information, see [NuGet package restore](../tools/dotnet-restore.md). -## Manage Visual Studio and MSBuild versions - -### Visual Studio side-by-side installation - -Visual Studio supports side-by-side installation of multiple versions. You can install Visual Studio 2022 and Visual Studio 2019 on the same machine, or multiple releases of Visual Studio 2022 (for example, 17.8 and 17.12). +### Control MSBuild version -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). +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). -Key points: +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. -- Visual Studio updates don't affect separately installed .NET SDKs. -- Use *global.json* to control which SDK version is used, regardless of the Visual Studio version. -- Each Visual Studio instance can have different settings and extensions. - -### MSBuild versioning - -MSBuild versions correspond to Visual Studio versions: - -- Visual Studio 2022 version 17.8 includes MSBuild 17.8 -- Visual Studio 2022 version 17.12 includes MSBuild 17.12 - -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. - -To specify a specific MSBuild version: +To use a specific MSBuild version: - Use `dotnet build` with a pinned SDK version in *global.json*. - Launch the appropriate Visual Studio Developer Command Prompt, which sets up the environment for that Visual Studio version's MSBuild. @@ -271,66 +209,6 @@ To specify a specific MSBuild version: For more information, see [.NET SDK, MSBuild, and Visual Studio versioning](../porting/versioning-sdk-msbuild-vs.md). -## Upgrade readiness checklist - -Before upgrading to a new .NET version or development environment, use this checklist to ensure a smooth transition: - -### Pre-upgrade assessment - -- [ ] Review the [breaking changes](../compatibility/9.0.md) for the new .NET version. -- [ ] Check if your NuGet packages support the new .NET version. -- [ ] Verify that any third-party tools and libraries are compatible. -- [ ] Review the [.NET support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) for the versions you're using and upgrading to. - -### Version pinning setup - -- [ ] Create or update *global.json* to pin the SDK version. -- [ ] Set `AnalysisLevel` to lock analyzer rules to the current version. -- [ ] Enable package lock files (`RestorePackagesWithLockFile`) for consistent package versions. -- [ ] Consider setting up Central Package Management if managing multiple projects. -- [ ] Configure package source mapping if using multiple NuGet feeds. - -### Development environment - -- [ ] Install the new .NET SDK version. -- [ ] Update Visual Studio (if applicable) or install it side-by-side with existing versions. -- [ ] Update IDE extensions and tools. -- [ ] Verify that your CI/CD pipeline can use the new SDK version. - -### Code changes - -- [ ] Update `TargetFramework` (or `TargetFrameworks`) in project files. -- [ ] Run `dotnet restore` to restore packages with the new framework. -- [ ] Build the project and address any errors or warnings. -- [ ] Run tests to ensure functionality is preserved. -- [ ] Update code to address any breaking changes. - -### Gradual rollout - -- [ ] Update non-critical projects first to identify issues. -- [ ] Test in a non-production environment before deploying. -- [ ] Update *global.json* and `AnalysisLevel` to allow newer SDK and analyzer versions gradually. -- [ ] Review and address new analyzer warnings over time. -- [ ] Update package versions incrementally to manage risk. - -### CI/CD and deployment - -- [ ] Update CI/CD pipelines with the new SDK version. -- [ ] Update Docker base images if using containers. -- [ ] Verify that the hosting environment supports the new runtime version. -- [ ] Test the deployment process in a staging environment. - -## Workload-specific migration guides - -Different .NET workloads might have specific upgrade considerations: - -- **ASP.NET Core**: [Migrate from ASP.NET Core (version) to (version)](/aspnet/core/migration/) -- **Entity Framework Core**: [Upgrading from previous versions to EF Core (version)](/ef/core/what-is-new/ef-core-9.0/breaking-changes) -- **.NET MAUI**: [Upgrading .NET MAUI applications](https://github.com/dotnet/maui/wiki/Upgrading-.NET-MAUI-from-.NET-7-to-.NET-8) -- **Blazor**: Included in ASP.NET Core migration guides -- **Windows Forms and WPF**: [Upgrade a Windows desktop app to .NET](/dotnet/desktop/migration/) -- **.NET Upgrade Assistant**: [Overview of the .NET Upgrade Assistant](../porting/upgrade-assistant-overview.md) - ## Update continuous integration (CI) 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. @@ -348,3 +226,8 @@ FROM mcr.microsoft.com/dotnet/aspnet:9.0 ``` In a cloud service like [Azure App Service](/azure/app-service/quickstart-dotnetcore), a configuration change is needed. + +## See also + +- [Breaking changes in .NET 10](../compatibility/10.0.md) +- [Migrate an ASP.NET Core app](/aspnet/core/migration/) diff --git a/docs/fundamentals/code-analysis/configuration-options.md b/docs/fundamentals/code-analysis/configuration-options.md index 031c5a9a712f1..662aac41be0bd 100644 --- a/docs/fundamentals/code-analysis/configuration-options.md +++ b/docs/fundamentals/code-analysis/configuration-options.md @@ -78,14 +78,14 @@ Rule-specific options can be applied to a single rule, a set of rules, or all ru 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. -| Severity configuration value | Build-time behavior | -|-|-| -| `error` | Violations appear as build *errors* and cause builds to fail.| -| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). | -| `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.) | -| `silent` | Violations aren't visible to the user.

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. | -| `none` | Rule is suppressed completely.

However, for code-style rules, Visual Studio code-generation features still generate code in this style. | -| `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`. | +| Severity configuration value | Build-time behavior | +|------------------------------|---------------------------------------------------------------| +| `error` | Violations appear as build *errors* and cause builds to fail. | +| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). | +| `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.) | +| `silent` | Violations aren't visible to the user.

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. | +| `none` | Rule is suppressed completely.

However, for code-style rules, Visual Studio code-generation features still generate code in this style. | +| `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`. | #### Scope From 3728f4beb03860e11d04bdfa0640c12efc25691c Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 28 Oct 2025 17:41:44 -0700 Subject: [PATCH 4/4] tweaks --- docs/core/install/upgrade.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/core/install/upgrade.md b/docs/core/install/upgrade.md index bc58911523864..c4159da908a94 100644 --- a/docs/core/install/upgrade.md +++ b/docs/core/install/upgrade.md @@ -15,10 +15,6 @@ Common reasons to upgrade to a new .NET version: - The new version supports a new operating system - The new version has an important API, performance, or security feature -## Controlled upgrades and version pinning - -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](#version-pinning), you can upgrade your development environment while maintaining control over when specific components are updated in your projects. - ## Upgrade development environment To upgrade to a new .NET version, the .NET SDK is the primary component to install. It includes an updated .NET CLI, build system, and runtime version. @@ -58,6 +54,8 @@ More resources: ## Version pinning +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. + Version pinning provides several benefits: - **Predictable builds**: Ensures consistent build results across different machines and CI/CD environments. @@ -116,6 +114,10 @@ For more information, see [AnalysisLevel](../project-sdk/msbuild-props.md#analys By managing package versions consistently across projects, you can prevent unexpected updates and maintain reliable builds. +- [Package lock files](#package-lock-files) +- [Central package management](#central-package-management) +- [Package source mapping](#package-source-mapping) + #### Package lock files 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. @@ -158,7 +160,7 @@ Create a *Directory.Packages.props* file in your solution root: ``` -In your project files, reference packages without specifying versions: +In your project files, reference packages without specifying a version: ```xml