Expand upgrade documentation with version pinning and controlled upgrade guidance

[Copilot]

Addresses #355904. Developers upgrading to new .NET/Visual Studio versions face unexpected analyzer warnings, SDK behavior changes, and breaking changes that disrupt builds. The existing upgrade documentation only covered high-level steps without guidance on controlling these transitions.

New Sections

• Controlled upgrades and version pinning - Why pinning matters: predictable builds, gradual adoption, team coordination
• SDK version control with global.json - Pinning SDK versions with rollForward policies (disable, patch, feature, latestFeature, latestMinor)
• Analyzer version control - AnalysisLevel and AnalysisMode properties for locking analyzer rules to specific .NET versions
• NuGet package version management - Package lock files, Central Package Management (Directory.Packages.props), Package Source Mapping
• Visual Studio and MSBuild versioning - Side-by-side installations, MSBuild version selection strategies
• Upgrade readiness checklist - Pre-upgrade assessment, version pinning setup, development environment, code changes, gradual rollout, CI/CD deployment
• Workload-specific migration guides - Links to ASP.NET Core, EF Core, MAUI, Blazor, WinForms/WPF, Upgrade Assistant documentation

Example: Pinning SDK and Analyzer Versions

// global.json - Pin SDK to 9.0.x
{
  "sdk": {
    "version": "9.0.100",
    "rollForward": "latestFeature"
  }
}

<!-- Project file - Lock analyzer rules to .NET 8 -->
<PropertyGroup>
  <AnalysisLevel>8.0</AnalysisLevel>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

This allows upgrading Visual Studio 17.12 and .NET 9 SDK while maintaining stable builds until ready to adopt new features incrementally.

---

cc @baronfel @rainersigwald @jaredpar @anangaur @zivkan

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Expand upgrade documentation to include specifics about pinning SDK, tooling, packages, and more.</issue_title>
<issue_description>### Type of issue

Missing information

Description

https://learn.microsoft.com/dotnet/core/install/upgrade currently provides very high level guidance to upgrading projects for each major .NET version.

There however are many more challenges that one may face when they use new IDE, editor, etc experiences that we should document some further best practices on.

We should inform users how to "pin" to certain versions of tooling, sdk, packages, etc so that they know that if/when new capabilities are provided in tooling, they can upgrade fearlessly and be able to build while they slowly upgrade these components on the new versions of tooling.

Some ideas for this doc:

• Why pinning matters (avoiding unexpected "breaking changes" or new behaviors. how it allows for controlled, incremental adoption of new features)
• Add AnalysisLevel, SDKAnalysisLevel, global.json, package lock files, central package management, package source mapping, etc
• Managing VS components and SxS versions
• Specifying specific versions of MSBuild
• Checklist to determine readiness for a VS / .NET SDK update (i.e. .NET 8 -> .NET 9)
• Any further documents on specific migration/upgrades for certain workloads (ASP.NET / EF / MAUI / etc)

This document is inspired by the .NET 9/VS 17.12 release.

Relevant areas:

• @baronfel for SDK/tooling,
• @rainersigwald for MSBuild,
• @jaredpar for Roslyn/analyzers
• @anangaur for upgrade assistant
• @zivkan for nuget
• ...???

Page URL

https://learn.microsoft.com/en-us/dotnet/core/install/upgrade

Content source URL

https://github.com/dotnet/docs/blob/main/docs/core/install/upgrade.md

Document Version Independent Id

a20fa96c-6d92-d941-f6d0-bf0369028e7f

Article author

@gewarren

Metadata

• ID: 327f5330-9be0-25fe-1e75-3673f7809d0d
• Service: dotnet-fundamentals
• Sub-service: install

Related Issues

---

Associated WorkItem - 355904</issue_description>

Comments on the Issue (you are @copilot in this section)

@gewarren @adegeo @adegeo @JonDouglas Great ideas for updating this doc. Should we break this up into sub issues? You have a lot of great concepts here that we'll need to gather more data on. @adegeo @gewarren Were you going to take this over? I think we decided on that.

• Fixes Expand upgrade documentation to include specifics about pinning SDK, tooling, packages, and more. #43688

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/install/upgrade.md	Upgrade to a new .NET version
docs/fundamentals/code-analysis/configuration-options.md	Configure code analysis rules

[Copilot]

Pull Request Overview

This PR adds comprehensive documentation on version pinning strategies for .NET development and formats a table in the code analysis configuration options document. The PR enhances the upgrade guide with detailed instructions for maintaining build predictability while upgrading development tools.

Key changes include:

• Added new "Controlled upgrades and version pinning" and "Version pinning" sections with detailed guidance
• Added ai-usage: ai-assisted frontmatter to indicate AI assistance
• Reformatted a severity configuration table for improved alignment

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/fundamentals/code-analysis/configuration-options.md	Reformatted the severity configuration table with improved column alignment
docs/core/install/upgrade.md	Added comprehensive version pinning documentation covering SDK, analyzers, NuGet packages, and MSBuild version control

[wadepickett]

Approved. Looks great to me.

• Clear, actionable, technically correct, and well placed in appropriate sections.
• Code samples look good.

A duplicate of a link is provided in the See Also, but that is a really minor item, and might be worth restating at the bottom of the doc anyway.