Expand upgrade documentation to include specifics about pinning SDK, tooling, packages, and more.

[JonDouglas]

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

[gewarren]

@adegeo