What is the .NET Upgrade Assistant?
- 5 minutes
In this unit, you'll learn how the .NET Upgrade Assistant can help you analyze your existing ASP.NET applications and plan your upgrade to ASP.NET Core.
The .NET Upgrade Assistant is a tool that helps you upgrade different kinds of application from older versions of .NET Framework, .NET Core, .NET 5, and .NET 6 to the latest .NET version. It's available in two "flavors": A Visual Studio extension and a CLI tool. After running Upgrade Assistant, in some cases the app requires additional effort to complete the upgrade. The tool receives constant updates with additional analyzers that automate fixes for breaking changes and simplify the upgrade process, so make sure you have the latest version of the tool.
The Visual Studio extension is convenient and provides graphical feedback throughout the upgrade, so in this unit we'll show how to use the extension. Meanwhile, if you prefer to use CLI, the documentation and installer are available on GitHub.
To follow along, you'll need to download and install the Visual Studio extension:
The tool supports the following .NET Framework app types:
- Windows Forms apps
- WPF apps
- ASP.NET MVC apps
- ASP.NET Web API apps
- Console apps
- Class libraries
It upgrades apps from the following versions of .NET:
- .NET Framework
- .NET Core
- .NET 5
- .NET 6
- .NET 7
to the latest Standard Term Support (STS), Long Term Support (LTS), or Preview versions of .NET.
The command-line version of Upgrade Assistant tool also supports upgrades:
- from Xamarin.Forms to .NET MAUI
- from WCF to Core WCF
Upgrade steps performed by the Upgrade Assistant
When upgrading a solution, the tool:
- Determines which projects need upgraded and recommends the order in which projects should be upgraded.
- Updates the project file to be an SDK-style project.
- Removes transitive NuGet package dependencies that might have been present in
packages.config. - Re-targets project to Standard Term Support (STS), Long Term Support (LTS), or Preview.
- Updates NuGet package dependencies to versions that are compatible with STS, LTS, or Preview.
- Makes simple updates in C# source code to replace patterns that worked in .NET Framework with STS, LTS, or Preview equivalents.
- For some app models (like ASP.NET apps), adds common template files (like Startup.cs) and makes simple updates based on recognized web.config or app.config values.
- For projects targeting Windows, adds a reference to the
Microsoft.Windows.Compatibilitypackage.
Tip
The Upgrade Assistant and upgrade documentation make repeated references to TFM. TFM is an abbreviation for Target Framework Moniker, and is used to indicate the set of APIs available to a project or library. Some example TFM's include net48 for .NET Framework 4.8 and net7.0 for .NET 7.0. The Upgrade Assistant will handle the TFM conversion in your project file for you.
Troubleshooting tips
Several known problems can occur when using the .NET Upgrade Assistant. In some cases, these are problems with the try-convert tool that the .NET Upgrade Assistant uses internally.
The tool's GitHub repository has more troubleshooting tips and known issues.