How to Migrate to Latest .NET Core Version Using Upgrade Assistant

This is an article how to upgrade to latest .NET core version using Upgrade Assistant offer.

What does it offer ?

The .NET Framework is the original implementation of .NET. A lot of projects are still running on that platform. Currently, the .NET Framework is supported and it comes as a part of Windows. Then the modern .NET came. The modern .NET is cross-platform implementation of .NET.

Both implementations can be used to create the web applications, Web APIs, Desktop applications, etc. Currently there are many applications that are still running on the original implementation of .NET, i.e. .NET Framework.

In the previous article, we discussed about migrating your ASP.NET to latest ASP.NET Core 3 version.

Migrating from .NET Framework to modern cross-platform .NET is bit tougher job. The .NET Framework heavily used the APIs which are supported on Windows and those APIs were not supported on platforms like Linux or MacOS.

Long story short, when an application based on .NET Framework is being migrated to modern .NET, we may come across many breaking changes. Such migration may need a lot of efforts if it has to be done manually.

Naturally, the next question should be, how can we save those efforts ? We can save efforts only via automation (or by not doing the intended work ? ) .

There comes the .NET Upgrade tool. The .NET Upgrade Assistant is a tool, which can be used to upgrade the .NET Framework based applications to modern cross-platform .NET platform.

Which kind of projects are supported ?

As stated earlier, this tool is to migrate the .NET Framework based projects to latest and greatest cross-platform .NET. As of today, the library supports the code written only in two languages – C# and VB.NET. Also, the tool supports the following .NET Framework project types:

Windows Forms apps
WPF apps
ASP.NET MVC apps
Console apps
Class libraries
Xamarin.Forms to .NET MAUI

It is an open source project and it is hosted in this GitHub repository. This tool allows upgrading to Latest, LTS or Preview versions of .NET.

What does it do ?

This is basically a command line tool. There are two entry points – Analyze and Upgrade.

Analyze

Analyze, as the name suggests can be helpful to perform the analysis on an existing solution. It can help in finding which NuGet packages, project references and framework references need to be added / removed / upgraded.

Analysis will also try to call out the unsupported APIs – the APIs which are used in the existing codebase, but not supported in Target Framework Moniker (TFM). It may also highlight the package upgrades, that could have breaking changes.

All this analysis is exported in the form of a report. This report can be in the SARIF format or HTML format. There is a switch in the command, that can be used to set which format of report is required. The SARIF report can be viewed in any text editor (like Notepad or Notepad++). Visual studio marketplace has extension – Microsoft SARIF Viewer – which provides richer user experience.

Upgrade

This entry point is for performing some modifications to the solution. The tool will determine which projects need the upgrades. It will also recommend the order in which projects should be upgraded.

The CSPROJ file format is different in modern .NET and hence the tool tries to upgrade the CSPROJ format. Older projects used to have NuGet package dependencies stored in packages.config. This tool helps in removing transitive dependencies.

The tool will also update CSPROJ file and will update the target framework moniker (TFM) to latest, preview or LTS version.

The beautiful part is it will try to update many things automatically including:

Package dependencies are updated to the versions compatible with .NET
Simple C# source code updates to replace .NET Framework templates and patterns with current, LTS or preview equivalent
Some additional source code may get added if it is required by the project type (for example startup.cs in ASP .NET Core projects).
For projects which target to windows, a reference to Microsoft.Windows.Compatibility package would be added
There are some analyzers which would help with the upgrade (e.g. Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers package). This tool may add references to this package.

As the tool is going to change the source code, this tool may leave the solution into a state where source code is not building or tests are broken.

So, after running upgrade tool, it would be needed to perform some kind of manual work to fix those things and verify the modifications. The analyzers help in highlighting remaining modifications and hence they would help in such manual work.

Prerequisites

Commands: Installation and Usage

If the .NET is installed correctly, the .NET CLI would also be installed. We can verify if .NET CLI is installed or not, by running dotnet command and then hitting ENTER. It should show you options for the command.

Below commands can be used for installing the upgrade assistant.

## Install the .NET Upgrade Assistant
dotnet tool install -g upgrade-assistant

## Update the .NET Upgrade Assistant
dotnet tool update -g upgrade-assistant

## Uninstall the .NET Upgrade Assistant
dotnet tool uninstall -g upgrade-assistant

## Analyze
upgrade-assistant analyze {Path to csproj or sln to upgrade}

## Analyze Example
upgrade-assistant analyze C:\\GitHub\\DotnetFramework.sln

## Upgrade
upgrade-assistant upgrade {Path to csproj or sln to upgrade}

## Upgrade Example
upgrade-assistant upgrade C:\\GitHub\\DotnetFramework.sln

Demos

There are already very good samples already available as a part of documentation. Below are some demos that we may want to refer are:

Connecting to private NuGet repository

As said earlier, the package references are upgraded by .NET upgrade assistant. Many solutions may have their own private NuGet repository setup. For connecting to such repositories, additional authentication configurations would be required. Please refer the documentation.

Conclusion

I hope you find this information helpful. Are you planning a .NET upgrade ? What are your thoughts ? What challenges are you facing ? Let me know in the comments.