In the previous post, I have tried to jot down few concepts related to .NET upgrade. While working on that post, I also got to know about the .NET Upgrade Assistant. That’s why this article is to explore that .NET Upgrade Assistant offers.
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 from modern .NET implementation’s older versions (like .NET Core 3.1, .NET 5, etc.) to the latest .NET 6.
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, 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.
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.csin 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.
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.
There are already very good samples already available as a part of documentation. Below are some demos that we may want to refer are:
- Upgrade an ASP.NET MVC App to .NET 6 with the .NET Upgrade Assistant
- Upgrade a Windows Forms App to .NET 6 with the .NET Upgrade Assistant
- Upgrade a WPF App to .NET 6 with the .NET Upgrade Assistant
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.
In addition to this there is a free e-book available – Porting existing ASP.NET apps to .NET Core. I think this may be good reading if we want to know more on this topic.
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.