Every year there is a new .NET version with improved performance, bug fixes, security fixes, and new features. What’s exciting for developers building cutting-edge applications can frustrate developers working on existing legacy.NET applications.
The .NET Upgrade Assistant is a tool created by Microsoft that helps with the migration from an older .NET version, including .NET Framework, to the latest .NET version.
When I talk to developers maintaining older .NET applications, I find out that one of the issues why they don’t use the latest .NET version is that they have a hard time upgrading or cannot even upgrade. Also, most developers have never heard of the .NET Upgrade Assistant.
I recently ran this poll on Twitter, and 60% of the voters said they don’t know the .NET Upgrade Assistant.
I want to change that, and I will explain the .NET Upgrade Assistant, where to get it, how to use it, and most importantly, how it helps migrate your legacy .NET applications.
What Type of Applications Can You Migrate?
Before we learn where to get and how to use the .NET Upgrade Assistant, let’s first learn what it can do for us.
It currently supports migrating different types of .NET applications, including:
- ASP.NET MVC
- Windows Forms
- Windows Presentation Foundation (WPF)
- Console App
- UWP Apps to Window App SDK (WinUI)
- Xamarin.Forms to .NET MAUI
- Azure Functions
- Class Libraries
The tool supports C# and Visual Basic .NET projects.
Getting the .NET Upgrade Assistant
The .NET Upgrade Assistant can be used in two different ways. We learn about them on the GitHub repository of the .NET Upgrade Assistant.
You can download it and use it as a stand-alone .NET CLI tool.
Alternatively, you can download a Visual Studio extension from the Visual Studio marketplace.
For both options, make sure you have msbuild installed. It’s a requirement for the .NET Upgrade Assistant. If you already have Visual Studio installed, msbuild should already be installed. Otherwise, download and install it first.
The GitHub page is also a great place to learn how to migrate your application. It contains links to migration guides, such as upgrading an existing WinForms application to .NET 6 or later.
Analyzing a Solution Before Upgrade
When running the analyze command, the .NET Upgrade Assistant can be used to analyze project dependencies before migrating the application.
The generated analysis report contains details about package dependencies that must be removed, added, or upgraded.
It sometimes also points out breaking changes and unsupported APIs and how to replace them.
For example, I ran the analyze command on a WPF application targeting the .NET Framework 4.6.
You can open the generated .sarif file using Visual Studio Code using the Sarif Viewer extension.
As we can see, the report contains a set of items for each project within the solution.
We get a list of tasks that we need to complete before migrating the application. In this case, we need to update a few packages to the .NET Framework 4.8 before migrating.
We also get suggestions to delete and add new package references.
For this application, we get a list of 39 actions we need to perform before migrating the solution.
The Upgrade Solution Command
The upgrade command starts the migration of an application.
It will discover what projects need to be upgraded and recommend an order in which projects should be upgraded.
If necessary, it will update the project files to the SDK-style project file format, and it will retarget the projects to the desired .NET version.
It will also upgrade NuGet package dependencies to versions that are compatible with the desired .NET version.
Sometimes, it will make subtle changes to source code written for the .NET Framework to work on newer .NET versions.
It will also add a reference to a code analyzer that will help with upgrading.
After running the tool, the solution will most likely not build until the upgrade is completed with manual steps.
Upgrading a Solution
I’m not the developer of the application I previously ran the analyze command on. I couldn’t run the upgrade command because the work required to prepare this application was too much.
However, the result of each migration will anyway be different depending on the application type and source code.
I have another solution that contains an ASP.NET Core WebAPI project and an Azure Function app. I will use the CLI to run the .NET Upgrade Assistant on this solution.
When starting the migration, the .NET Upgrade Assistant asks for an entry point. In my solution, there are two applications, and I have to select the application I want to upgrade.
In the end, I want both applications to be migrated. Therefore, I have to run the .NET Upgrade Assistant for each application within the solution.
There is a number of steps that are performed. Depending on the application type, it can be more or less user input required.
When the migration is completed, there will be another .serif file containing a migration report with further instructions.
If all goes well and all manual tasks have been performed, the application should finally run on the specified .NET version.
CLI vs. Visual Studio Extension
Be aware that at the time of recording, the Visual Studio Extension has a few features currently unavailable in the CLI version.
However, the .NET team has already announced in a blog post that they will work on bringing those missing features into the CLI soon.
I’d suggest trying both options to see what works best in your scenario.
Conclusion
How much the .NET Upgrade Assistant can help when migrating to the latest .NET version certainly depends on the application type.
Depending on the application type, you might have to do more or less manual work, such as updating or replacing external dependencies, before or after the migration. However, the .NET Upgrade Assistant helps you identify what you need to work on.
In the end, it’s just a tool. But used the right way, it can be really helpful and save you hours, if not days when migrating from an older .NET version to the latest .NET release.
If you want to learn more about .NET development, consider subscribing to my YouTube channel.
