Migrate or Port Your Old Legacy .NET Projects to the .NET5

The word migration means a lot to us, developers, every day we upgrade ourselves by learning new technologies and the situation should not be different when we work on the legacy application. That’s when the use of some cool migration tools coming into the picture. If you are looking for a tool to migrate your legacy old .NET framework projects to the .NET5 version, then you are in the right place. Recently, I got a chance to migrate one legacy application to .NET5, and here in this post, I will be explaining the steps. Throughout the process, I will be using two different tools, “Porting assistant for .NET” by Amazon and .NET Upgrade Assistant by Microsoft. Both tools are Open Source and maintained by the community, free to use. Let’s get started.

Prerequisites

Download the Targeting framework, and install it. In my case, NET5. You can download them from here.

Upgrade Assistant tool by Microsoft

If you choose to use the Upgrade Assistant tool by Microsoft, all you have to do is to install visual studio, install the try-convert tool by running the preceding command.

Install try-convert: dotnet tool install -g try-convert
Update try-convert: dotnet tool update -g try-convert

Now install the upgrade assistant by executing the below command.

dotnet tool install -g upgrade-assistant

Just like any other tools, to update the tool, just run the below command.

dotnet tool update -g upgrade-assistant

To get more info about the installation, you can visit this document.

Porting Assistant tool by Amazon

If choose to use this tool, please make sure that you have done the preceding things.

  • Signup an account with AWS
  • Log in to the AWS account and collect the security credentials. We will be using this info in our migration. Visit this site, click on the Access Keys section, and then click on the Create New Access Key button. This will generate a new key, download the same and keep it in a safe location.
Amazon access keys
  • Go to this link, click on the Download Porting Assistant for the .NET button to download and install. You can also use the Visual Studio extension from here.

Port the Application

In this section, let’s see how we can use both tools.

Using Upgrade Assistant tool

Using the upgrade assistant tool is as easy as you type some writing some basic commands in CLI. If you have worked with any CLI tools before, this would be very easy.

Once you have installed the tool, you can run the preceding command to start the process.

upgrade-assistant upgrade <Path to csproj or sln to upgrade>

This will analyse your solution or the project and give you the commands to perform as in the preceding image. The first step is to select the entry point from your solution, if you are trying to port the entire solution.

Upgrade Assistant initial commands

The next step is to select the project and select the commands to perform each task. Please remember that you will have to do this for each project. In my case, I was having 43 projects, if you have more projects it can be a pain. Your screen should look like the preceding image.

Upgrade Assistant porting task

Please keep in mind that I am upgrading my MVC application, and the commands will be slightly different for other .NET framework app types. See more here. Once the tool has gone through all the projects, the last step is to finalize the upgrade. As always, all you have to do is selecting the command.

Upgrade assistant finalize step

You should get a message as preceding once the upgrade has been completed.

[22:43:27 INF] Upgrade has completed. Please review any changes.
[22:43:27 INF] Deleting upgrade progress file at C:\sourcecode\solution-name.upgrade-assistant
PS C:\sourcecode\solution-name>

Upgrade output

It is worth noting that you will have to manually do a lot of changes in your solution according to how complex your solution is. Some of the warnings/errors that this tool gives are given below.

  • No version of System.Configuration.ConfigurationManager found that supports [“net46”]; leaving unchanged
  • No version of System.ServiceModel.Federation found that supports [“net46”]; leaving unchanged
  • .NET Upgrade Assistant analyzer NuGet package reference cannot be added because the package cannot be found
  • Package AutoMapper has been upgraded across major versions (4.2.0 -> 5.2.0) which may introduce breaking changes
  • No version of EnterpriseLibrary.TransientFaultHandling found that supports [“net5.0-windows”]; leaving unchanged
  • No version of EnterpriseLibrary.TransientFaultHandling.Data found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.AspNet.WebApi.OData found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.Azure.CosmosDB.Table found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.Azure.DocumentDB found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.Bcl.Async found that supports [“net5.0-windows”]; leaving unchanged
  • Package Microsoft.Web.Xdt has been upgraded across major versions (2.1.1 -> 3.1.0) which may introduce breaking changes
  • Package Microsoft.Azure.NotificationHubs has been upgraded across major versions (1.0.9 -> 2.0.2) which may introduce breaking changes
  • No version of SharePointPnPCoreOnline found that supports [“net5.0-windows”]; leaving unchanged
  • Package Microsoft.Azure.NotificationHubs has been upgraded across major versions (1.0.9 -> 2.0.2) which may introduce breaking changes
  • No version of System.ServiceModel.Federation found that supports [“net46”]; leaving unchanged
  • No version of Microsoft.Azure.ActiveDirectory.GraphClient found that supports [“net5.0-windows”]; leaving unchanged
  • Package Microsoft.Azure.WebJobs has been upgraded across major versions (1.1.2 -> 2.3.0) which may introduce breaking changes
  • No version of Microsoft.ApplicationInsights.Web found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.AspNet.WebApi.Owin found that supports [“net5.0-windows”]; leaving unchanged
  • No version of StackifyHttpModule found that supports [“net5.0-windows”]; leaving unchanged
  • No version of System.IdentityModel.Tokens.ValidatingIssuerNameRegistry found that supports [“net5.0-windows”]; leaving unchanged
  • No version of WebApiContrib.Formatting.Jsonp found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.AspNet.WebApi.Cors found that supports [“net5.0-windows”]; leaving unchanged
  • No version of Microsoft.AspNet.WebApi.Tracing found that supports [“net5.0-windows”]; leaving unchanged
  • Package NJsonSchema.CodeGeneration has been upgraded across major versions (1.39.5923.31344 -> 2.65.6055.39156) which may introduce breaking changes

Using Posting Assistant tool

This is how you can use the Porting Assistant tool.

Configure the Porting Assistant tool

Once the tool is installed, open the same and click on the Get started button.

Get started with Porting Assistant for .NET tool

In the new screen, select the target framework and then click on the Add named profile link and provide the Access key information we get from the AWS console.

AWS named profile

Click on the Add button, if you want to know more about the named profile, this has everything documented. This is how your screen should look like now.

Porting assistant framework selection

Using the porting assistant tool

From the above screen, click on the button Next. From here you can select your solution file that holds all of your projects. The tool will start analysing your solution bytes by bytes, depending on the complexity of your solution, this can take a while.

Porting assistant tool analyse screen

The system will give a message as in the preceding image once the analysing is finished. The screen will also contain information about your Incompatible packages, Incompatible APIs, Build Errors, Porting actions, etc.

Porting assistant tool success message

Click on the solution name, in the screen you will be able to either select all the projects or one by one at a time and start the porting process.

Porting assistant porting action

Clicking on the button Port solution redirect you to another screen, that is where you can change the versions of your packages. And once you finalized that, click on the port button. You should now see a notification saying that the porting has started.

Porting assistant porting operation

You will also be getting an option to view the logs at the end.

Things to keep in mind

  • These tools are just a starting point, and according to the complexity of your application, and the number of APIs or packages incompatible, you may have to manually edit the code and change the package references.
  • It will be helpful if you choose to save the accessed solution in the same place if you use any Git branch so that you can see the changes and act accordingly.
  • If you use Microsoft Upgrade Assistant, you can choose the given order to perform the port or if you use Amazon Porting Assistant, you can select which project you should be migrated first according to the graph in the Project references tab.

More information about the tools

The .NET Upgrade Assistant is a CLI tool introduced by Microsoft, and with this tool, you can easily migrate any old application to new versions. You can read more about this tool here.

The tool “Porting Assistant for .NET” is developed by Amazon. You can read more about this tool here.

To get more understanding about this “Porting Assistant for .NET” tool, I recommend you to watch the preceding video.

Porting Assistant for .NET Overview

Conclusion

In this post, we learned the preceding things.

  • What is Upgrade Assistant tool from Microsoft
  • How to configure and use Upgrade Assistant tool from Microsoft
  • How to migrate from old .NET framework project to new .NET 5 version
  • What is the Porting Assistant for the .NET tool
  • How to configure the Porting Assistant for the .NET tool

I will be updating this post if I find any information needs to be added in the future.

About the Author

I am yet another developer who is passionate about writing and video creation. I have written close to 500 blogs on my blog. And I upload videos on my YouTube channels Njan Oru Malayali and Sibeesh Passion. Please feel free to follow me.

Your turn. What do you think?

Thanks a lot for reading. Did I miss anything that you may think is needed in this article? Could you find this post useful? Kindly do not forget to share your feedback.

Kindest Regards

Sibeesh Venu