Introduction

This guide aims to provide an iterative approach to migrating your .NET Framework projects to .NET 6+. An iterative approach means that your team can migrate from .NET Framework without halting regular production.

This guide does not cover specific differences and benefits/drawbacks of moving to .NET 6+.

This guide also assumes that you know the difference between .NET Framework, .NET Standard, .NET Core, and .NET. (see here)

Since .NET 6 and beyond is the newest naming scheme for the framework, .NET Core will not be explicitly mentioned, even though this guide should implicitly apply to those of you choosing to upgrade to .NET Core.

Prerequisites

Solution projects analysis

TL; DR: analyze your solution projects to get an overview of unsupported features requiring your attention

Microsoft provides a particularly useful tool for analyzing the portability of your .NET Framework projects to .NET 6+ called .NET Portability Analyzer (see msdoc). It is also available as a plugin for Visual Studio 2019 (see marketplace); unfortunately, there is no support for newer versions of the IDE.

1. Download the .NET Portability Analyzer from the provided link in msdoc
2. Extract the archive into a directory of your choice
3. Run the following command in the directory mentioned above: ./ApiPort.exe analyze -t “.NET, Version=6.0” -f path/to/your/project
4. The tool will generate the analysis report in the directory of its location
5. In the report you’ll find scores for individual projects. A score above 75% is what you are aiming for. Anything below will require more effort to migrate, and, in such cases, it might make sense to rewrite said projects anew
6. In the Details sheet you can find types and members not supported that you should investigate (some of the changes can be made during the migration; however, it is recommended to prepare for said changes by researching ahead)

Manual project tech stack analysis

TL; DR: gain a better understanding of where you stand and what obstacles wait ahead by answering the suggested set of questions

It is important to note all integrations, technologies, and so on, that your projects use. Here are some questions you should answer:

• Are you using third-party UI libraries?
• Are you referencing a third-party API library?
• Are your projects using WCF for API communication? Will I be limited by the available features of CoreWCF (see more)?
• Are there any C++/CLI projects (see msdoc)?
• Are you utilizing the CopyLocal option in your project references?
• Are you using any old .NET libraries such as
  • MEF,
  • MAF,
  • Enterprise Library?

Answering “yes” to each of those questions increases the complexity of your migration. The specifics of solving issues introduced by said questions will be covered in other articles.

Make sure you are not using any deprecated technology, such as ASP.NET Web Forms, this would mean a need to rewrite your whole application. In general, migrating UI-dependent projects is the most challenging task. Keep in mind that depending on your tech stack, you might not get the cross-platform benefit of .NET 6+.

Migrating to NuGet

TL; DR: ensure your CI process supports restoring NuGet packages and that your team knows how to use them.

Some of the references you get out-of-the-box in the .NET Framework had been cut and moved to separate NuGet packages, which can be downloaded and referenced on-demand. Upon migrating your projects, you shall stumble upon said missing references that can be easily resolved by searching and referencing relevant NuGet packages. Thus, it is necessary to prepare your infrastructure to support resolving said packages when building your projects.

Some of you might be accustomed to referencing additional libraries the classic way – downloading the libraries manually, keeping a copy in your VCS, and referencing them whenever needed. Please don’t do that. You’re making your job much more difficult; thus, you are less efficient and wasting precious time and money.

Moreover, using NuGet opens doors to a plethora of powerful packages. If your team/company uses in-house packages, you can streamline said package distribution by hosting your NuGet package feed (see msdocs).

If you already use NuGet, make sure that you migrate to PackageReference:

Migration steps

The following migration steps will help you prepare your projects for .NET 6+, and whenever you are ready, can simply make the switch from .NET Framework. However, said steps do not consider any complications introduced by answering “yes” to the questions in the Manual project tech stack analysis (above). Solutions for those problems will be covered in other articles.

1. Step1: Migrating to an SDK-style project