As we developers know, the legacy .Net Framework (<=4.8) has reached end of life. We now need to turn our attention towards migrating our codebase towards .Net Core 3.1 (LTS) or .Net 5 (Current). The steps in this article will also hold true for .Net 6, which is slated for release in November.

Check whether you can migrate to .net core

First, you will need to install the .Net Portability Analyzer. You can install this as a Visual Studio extension. Once it has installed, right click on the project you would like to migrate and choose

When the process has finished, you will be able to open a spreadsheet containing a compatibility report. If all is well, then you can continue.

Migrate the CSPROJ to the new SDK style project

First, ensure that you have the .net core sdk installed on your machine:

dotnet --version

If successful, it will output the current sdk verion you have. In my case it was 5.0.202

You now need to install the migration tool:

dotnet tool install --global Project2015To2017.Migrate2019.Tool

This is a 3rd party open source tool, but works well

Finally, run the migration wizard:

dotnet migrate-2019 wizard <path>

Remember to replace <path> with the full path to the csproj or solution file you are migrating. It may be easier if you open a command prompt from the solution / project folder that you are upgrading.

It will ask you if you would like to take a backup. If you are using source control (and have created a new branch), then there should be no need to do this. You will also be asked whether you would like “to modernise” the project. You should choose yes to this.

Once your project has been upgraded, this will give you an SDK style project, in the same version of the .Net framework that the original project was in.

Editing the project files

You will need to make some minor edits to the project files before they run under .Net5

Find the <TargetFramework> entry and modify it to <TargetFramework>net5.0</TargetFramework>

If your application uses Windows Forms, you need to make a couple of changes:

<TargetFramework>net5.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
<OutputType>WinExe</OutputType>

You may also need to add the following line in the ItemGroup containing ProjectReference

  <PackageReference Include="Microsoft.Windows.Compatibility" Version="5.0.2" />

This is to obtain access to a number of Windows SDK’s that are otherwise not compatible with .Net 5. Of course, your application may run fine without them.

Cleaning up

Once you have completed these steps, it is time to fire up Visual Studio again and load the solution. There may be some compilation errors after upgrade, This is because, in the new world, standard references like System.Data.SqlClient are now NuGet packages. You will need to install the packages you need.

You should also remember that your project is probably using the app.config configuration file rather than the newer appSettings.json. This is not in itself a problem and remains a perfectly valid configuration pattern.

Finally, build and test thoroughly remembering that if you reference any other projects, they will also need to be updated. You will also have to update your nuget packages.

Build and Deployment

If you are using a CI/CD pipeline for your project, you will also have to make changes to the build and package steps. Azure DevOps and TFS have built in dotnet core steps to help you through the process. Just remember to update your restore step, then use dotnet build –no-restore, dotnet test –no-build and finally dotnet publish –no-build to build, test and create artifacts as necessary.

Your deployment steps should not change too much, provided your publish step is correct.

Posted on: April 21, 2021, by : admin