Published on:Jul 28, 2021
Views: 2775
Number of votes: 10
Average rating:

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

Introduction to Optimizely .NET 5 Series

Welcome everyone to a series of posts about the upcoming releases of .Net 5 compatible commerce and content clouds.

Getting started with upgrade-assistant

Starting a new project

Working with docker and containers


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

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.  

Jul 28, 2021

Dejan Caric
( By Dejan Caric, 10/15/2021 10:08:59 AM)

The upgrade assistant will change the target framework, do some basic renaming, etc. but it doesn't upgrade episerver.cms to version 12, lots of files that need to be modified...

Doesn't work with Alloy.

Mark Hall
( By Mark Hall, 10/15/2021 7:16:20 PM)

It actually saves quite a bit of time having upgrades over 100 projects manually myself.  It is not meant to upgrade everything as that is not possibe with the changes between the frameworks.  As for the upgrade the package, threre is a bug on that in upgrae-assistant-extensions that I will try to fix soon.  Thanks for the feedback.

Please login to comment.