Jump-starting the Migration to .NET Core with Upgrade Assistant

Microsoft recently announced an Upgrade Assistant to help ease and speed up the transition to .NET Core. The release of this tool is a not-so-subtle nudge toward helping everyone get migrated from .NET Framework to .NET Core. The Upgrade Assistant builds off the try-convert tool by providing a user-directed flow as well as tools for handling transitioning multiple projects at once. I’ve decided to jump in and start using the Upgrade Assistant to see if it is a step up from try-convert.

Things to Consider Before Starting

The current state of the Upgrade Assistant will upgrade your projects from to the newer project structure and change the targeted framework to .NET Core. Along with migrating the project structure, Upgrade Assistant will apply some code changes in C# for ASP.NET projects. While these changes may not complete the migration for you, they are a step in the right direction with more rules coming in later iterations.

We’ve gone over what the Upgrade Assistant will do for you, but now we should talk about what it won’t do for you. Since the Upgrade Assistant is built on top of try-convert, it has the same limitations in code that cannot be migrated to .NET Core:

• Application domains
• Remoting
• Code access security (CAS)
• Security transparency
• System.EnterpriseServices

Migrating away from each of these concepts has their own in-depth process with trade-offs and redesigns that are best left to each individual use case. With the limitations out of the way, let’s jump into some best practices for setting yourself up for success.

There were a few lessons I learned that helped me out as I ran the Upgrade Assistant that may benefit everyone. Before running the tool, I verified that I had no active changes in my branch along with making sure there were no major changes that were currently happening soon or in-flight. This tool restructures the project files along with dependencies, so I wanted to make sure that there wouldn’t be any big issues re-merging it with the main branch.

Along with starting with a clean branch, I made an entire copy of the current solution folder. While copying a project that is already in source control seems like overkill, I find that viewing both files open side by side helps with seeing what is happening.

Running Upgrade Assistant

To install the tools, you’ll need to install upgrade-assistant and the easiest way to do it would be using the dotnet tool in powershell. There is a dependency on MSBuild, so if you are not running it on a machine with Visual Studio installed, you’ll need to install MSBuild.

dotnet tool install -g upgrade-assistant

Once installed, you can run the tool against your solution. When you run the tool against a solution, it will prompt you to select the entry-point project, which it will use to help generate the order that you should migrate your projects in.

upgrade-assistant.exe <solutionfile.sln>

WinForm (Windows Form App)

For WinForm migrations, the Upgrade Assistant will only upgrade the structure of the project and solution along with changing the target framework with references. At the current time, there are no rules explicit to change code with the projects. While this may seem like a small benefit, I have found that most WinForm projects tend to have a number of dependent projects over time, which this tool can help with migrating everything in the correct order.

ASP.NET MVC

When it comes to migrating an ASP.NET MVC app, the Upgrade Assistant has a few more rules in place to get you further along in the migration process. On top of migrating the projects, there is a set of rules that will be applied to your C# project.

Following up

After following the prompts in the Upgrade Assistant, you find yourself pressing <1> and <enter> quite a few times. Eventually, you’ll find that the migration is complete. It is possible for the Upgrade Assistant to complete successfully and still have some work left to complete the migration.

If the Upgrade Assistant has no failures, you can start running unit tests and testing the app to verify the changes before checking in the code. But, at this point you should be well on your way toward completing the migration.

If the Upgrade Assistant has failed, there are a few options that you can use to track down the differences and pick up where the process failed.

The first and simplest approach is to compare a diff of the current files to the previous files and see if there was an issue during the migration. During this investigation, you can fall back to rerunning the tool using the verbose flag (-v) to see the exact logs around the time of failure. If nothing comes out of this, you will at least have some very detailed logs to supply to Microsoft.

The most extreme approach is to keep the projects that migrated successfully, and restore from the backup folder that was created from the Upgrade Assistant. The backup folder takes a copy of the project before migration, so you should be able to delete the current <project_name> folder, and rename the <project_name>.backup to <project_name>.

Wrapping Up

Overall, the Upgrade Assistant is a pretty useful tool for getting you started in migrating your code to .NET Core. While it does provide a direct workflow, it is just a start for migrating your code. There may be parts that will need to be changed even after the framework migration to get everything working. But the upside is that the Upgrade Assistant is extensible and has a solid roadmap ahead, so it won’t be surprising to see user supplied extensions and new features coming out to make this tool even more useful. Happy coding!