Getting started with upgrade-assistant - .NET 5 Series, Part 1

Introduction

Welcome everyone to the first post in a series of posts about the upcoming releases of Optimizely .Net 5. In this post we will explore the upgrade-assistant tool from Microsoft.  This tool allows for developers to upgrade their .net full framework applications to .NET 5 and beyond.  It is also built to be extensible so ISV's can add extensions to make it easier to for their customers to upgrade their solutions.  Optimizely has created its own extension library to automate common Optimizely specific fixes when moving to .NET 5 and beyond.  Lets dive into how to use the tool to ugrade your solution.

Install Tools

Install the latest vesion of the upgrade-assistant

 dotnet tool install -g upgrade-assistant

or upgrade 

dotnet tool update -g upgrade-assistant

Grab the latest release of Optimizely upgrade-assistant-extensions and unzip the file to a location of your computer (ex C:\temp\epi.source.updater). Technically you should be able to point the zip file instead of extracting, but there seems to be a bug in upgrade-assisant at the moment for that.

Make sure to add the beta feed to you nuget config before running the tool.  Upgrade-asstant will use the defined package sources when looking for packages to update that are compatiable with .NET 5

https://pkgs.dev.azure.com/EpiserverEngineering/netCore/_packaging/beta-program/nuget/v3/index.json

Upgrade the solution

upgrade-assistant upgrade {projectName}.csproj --extension "{extensionPath}" --ignore-unsupported-features

You can point to solutiion file if you are upgrading more than project.  It is important to note that this tool is not meant to complete and handle all errors.  There are some fundamental differences between full framework and .NET 5 that make it impossible to automate everything.  It should however handle all the mundane repetitive tasks that can be automated, allowing the developer to worry about fixing the larger issues.  Also, after using a couple of times on solutions, I tend to use the non-interactive mode which speeds up the process.  I would not use this mode until you have used the tool a couple of times and understand what the tool is doing.

Closing Thoughts

I want to thank Microsoft for developing such a great tool.  We started with a couple ideas on how we could make the upgrade easier for our customers to .NET 5 and upgrade-assisant was the end result.  As I have been following the project, I have seen many nice additions in the journey to .NET 5 and beyond.  I am super exicted about the .NET Multi-platform App UI (MAUI) and see they are adding support for migrating WPF and Xarmin apps to the new maui framework through upgrade-assistant.