Always will be ready notify the world about expectations as easy as possible: job change page
Aug 26, 2021

Migrate from .NET Framework to .NET 5

Dumindu De Silva

What is .Net 5

.Net 5 is one of the major and latest releases of Microsoft’s .NET family. It comes with many exciting features compared to the previous released .Net core. The primary goal with the release of .Net 5 is to merge all future .Net development onto one unified platform. All of Microsoft’s different development environments, such as WPF, ASP. NET, Xamarin, etc. are all moving to .NET Core, which will now be known as “.NET”.

The latest version of .Net Core was named as .Net 5.0 to prevent confusion with the .Net framework versions already out there. So from now on, they plan to keep the versioning simple 5.0, 6.0, 7.0, and so on.

Why should you migrate from .Net Framework to .Net 5

Before diving into the why, Let’s look at some key features of .Net 5 include:

  • Cross-platform implementation.
  • Open-source & community-oriented.
  • Support with future updates to Visual Studio Code, Visual Studio 2019, Command Line Interface, and Visual Studio for Mac.
  • Support for platform-specific features like Windows Forms, & WPF on Windows.
  • Small project files.

With the consideration of the above features,

You may use NET Core/5+ for your application:

  • If you’re cross-platform needs.
  • If you’re targeting microservices.
  • If you plan to use Docker containers.
  • If you need high-performance and scalable systems.
  • If you need side-by-side .NET versions per application.

You better stay with .NET Framework for your application when:

  • If your app uses third-party .NET libraries or NuGet packages not available for .NET Core/5+.
  • If your app uses .NET Framework technologies that aren’t available for .NET Core/5+.
  • If your app uses a platform that doesn’t support .NET Core/5+

Determine the upgrade feasibility

Before you start, it’s better to become familiar with the upgrade feasibility of your project and understand which dependencies support DotNET 5. For this, we can use the .NET Portability Analyzer tool which is available at the Visual Studio Marketplace. This tool will analyze assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms.

Once you have installed the extension from Marketplace you can configure it in Visual Studio via Analyze > Portability Analyzer Settings and selecting your Target Platforms, that you want to evaluate the portability gaps comparing with the platform/version that your current assembly is built with.

To analyze your entire project in Visual Studio, right-click on your project in Solution Explorer and select Analyze Assembly Portability. Or else, go to the Analyze menu and select Analyze Assembly Portability. From there, select your project’s executable or DLL.

Analyze portability
Analyze portability

Portability Summary
Portability Summary

.NET Upgrade Assistant

Trust me, manually migrating your legacy .net framework project can be really hard. To make things easier, Microsoft previewed a new tool ‘.NET Upgrade Assistant’ in their Ignite event in 2021. The .NET Upgrade Assistant is a powerful global command-line tool that can be run on different kinds of .NET Framework apps. It’s designed to assist with upgrading .NET Framework apps to .NET 5. It will do most of your heavy lifting and allow you to focus on what’s important. The tool includes the installation of analyzers that can assist with completing the migration. The .NET Upgrade Assistant works on the following types of .NET Framework applications:

  • Windows Forms
  • WPF
  • Console apps
  • Class libraries

Before you start

Before you install the .NET Upgrade Assistant, you must ensure you install the following:

  • Visual Studio 2019 16.8 or later (Visual Studio is required because the tool uses MSBuild to work with project files)
  • The .NET 5 SDK

The tool also depends on the try-convert tool to convert project files to the SDK style.

  • You must have version 0.7.212201 or later to use the Upgrade Assistant.

From a terminal, run the following to install the try-convert. (It’s a global tool, so you can run the command anywhere.)

dotnet tool install -g try-convert

If you have try-convert installed but need to upgrade to a newer version, execute the following:

dotnet tool update -g try-convert

Install the .NET Upgrade Assistant

We’re now ready to install the .NET Upgrade Assistant. To do so, execute the following from a terminal:

dotnet tool install -g upgrade-assistant

After installing the .NET Upgrade Assistant, run it by navigating to the folder where your solution exists and entering the following command.

dotnet tool upgrade -g upgrade-assistant

Use the Upgrade Assistant to Migrate to .NET 5

To get started, Let’s run the following command from the terminal. (The default command should work, but, if needed, you can pass other flags like — verbose.)

upgrade-assistant upgrade <MySolution.sln>

The tool executes and shows you the steps it will perform. For each step in the process, you can apply the next step in the process, skip it, see details or configure logging. Most of the time, you’ll want to select Apply next step. To save some time, you can press Enter to do this.

Back-Up your Project

The first step is to back up the project. The .NET Upgrade Assistant asks if you want to use a custom path for your backup or a default location. Once this completes, we’re ready to convert the project file.


Convert Project files to SDK Style

.NET 5 projects use the SDK-style format. In this step, the Upgrade Assistant converts your project file to this SDK format using the try-convert tool. During this process, we see the tool is warning us that a few imports, like System.Web, might need manual intervention after migration.

Clean up NuGet package references

In this step, the Upgrade Assistant will update package references and remove transitive dependencies.

Update the target framework (Update TFM)

Next, the .NET Upgrade Assistant will update the Target Framework Moniker (TFM) to .NET 5.0. For example, net451 to net5.0.

Update NuGet Packages

Once the Upgrade Assistant updates the TFM, it attempts to update the project’s NuGet packages. The tool uses an analyzer to detect which references to remove and which packages to upgrade with their .NET 5 versions. Then, the tool updates the packages.

Add Template Files

After the tool updates any NuGet packages, it adds any relevant template files. ASP.NET Core uses template files for configuration and startup. These typically include Program.cs, Startup.cs, appsettings.json and appsettings.development.json based on recognised web.config or app.config values.

Migrate Application Configuration Files

  • Now the tool is ready to migrate our application configuration files. The tool identifies what settings are supported, then migrates any configurable settings to the appSettings.json file.
  • After that is complete, the tool migrates system.web.webPages.razor/pages/namespaces by updating _ViewImports.cshtml with an @addTagHelper reference to Microsoft.AspNetCore.Mvc.TagHelpers.

Update C# Source

Now, the .NET Upgrade Assistant upgrades C# code references to their .NET Core counterparts. You’ll see several steps listed in the terminal — not all apply. In those cases, they’ll be skipped over and flagged as [Complete].

As the first step, it removes any using statements that reference .NET Framework namespaces, like System.Web. Then, it ensures the ActionResult calls come from Microsoft.AspNetCore.Mvc namespace. Finally, the Upgrade Assistant ensures that I don’t use HttpContext.Current, which ASP.NET Core/5 doesn’t support.

The final step is to evaluate the next project. If there are no other projects left, the tool will exit.

Manually Fix Remaining Issues

Now you can open your project in visual studio and check whether your project has ported successfully to .Net 5 by, Right-click -> Properties in your project.

Let’s try to build this code. Look for warnings in the Error List window of Visual Studio to help you identify other parts of your code that might not be supported in .NET 5. A majority of these issues involve how ASP.NET Core handles startup, configuration, and bundling.

  • The Global.asax and Global.asax.cs files are no longer needed in ASP.NET Core, as the global application event model is replaced with ASP.NET Core’s dependency injection model, in Startup.cs.
  • You won’t need the App_Start folder or any of the files in it (BundleConfig.cs, FilterConfig.cs, and RouteConfig.cs). You can easily delete those files.
  • Finally, fix any issues that remain. You should also check any NuGet packages that might have been updated as sometimes there are breaking changes, and you may need to revert to an older version.


In this article, we discussed the difference between the .net framework and .net 5. Then we toured the new .NET Upgrade Assistant and showed how can we easily speed up your migration to .NET 5.

As I mentioned, the .NET Upgrade Assistant is a promising and powerful tool however, it’s in prerelease mode and developing gradually. Make sure to check out the tool’s GitHub repository to get up to speed and report any issues or suggestions.

Happy upgrading to .Net5!!!

Nov 19, 2020
Author: Ryszard Seniuta
Although SQL Server's Full-Text search is good for searching text that is within a database, there are better ways of implementing search if the text is less-well structured, or comes from a wide variety of sources or formats. Ryszard takes...
Feb 2
Author: Jeslur Rahman
If you are embarking on the journey to become a .NET Framework developer in 2024, you’re in for an exciting ride! The .NET ecosystem is vast and constantly evolving. To help you navigate this landscape effectively, we’ve compiled a comprehensive...
Aug 15, 2021
.NET has a large number of built in exceptions. However, there maybe times when none of the built exceptions seem adequate for your particular scenario and you will need to create your own custom (AKA “user defined”) exception.This post focuses...
Mar 12, 2021
Author: Bruno Joaquim
Exceptions are part of any software and can happen any time even where we are absolutely sure that nothing can go wrong. Exceptions are inevitable, we all agree with that. We should always deal with them in our applications to...
Написать сообщение

© 1999–2024 WebDynamics
1980–... Sergey Drozdov
Area of interests: .NET Framework | .NET Core | C# | ASP.NET | Windows Forms | WPF | HTML5 | CSS3 | jQuery | AJAX | Angular | React | MS SQL Server | Transact-SQL | ADO.NET | Entity Framework | IIS | OOP | OOA | OOD | WCF | WPF | MSMQ | MVC | MVP | MVVM | Design Patterns | Enterprise Architecture | Scrum | Kanban