Mark Hall
Jul 28, 2021
(10 votes)

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
Dejan Caric Oct 15, 2021 10:08 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
Mark Hall Oct 15, 2021 07:16 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.
Latest blogs
Optimizely shortcuts in CMS 12 will get a trailing slash appended!

Not all URLs will work when the trailing slash is added, and that could cause problems. Hopefully it will be fixed soon.

Tomas Hensrud Gulla | Nov 26, 2022 | Syndicated blog

One week left of the beta certification period

Today it's one week until the last beta certification day. Do you exam no later than Wednesday the 30th.  Here are the reference and exam guides:...

Karen McDougall | Nov 23, 2022

Unbelievable FREE Heatmapping With Optimizely Web

Within this guide, you will learn how to integrate a free heat mapping tool to Optimizely Web so you can turbocharge your A/B testing capabilities....

Jon Jones | Nov 22, 2022 | Syndicated blog

Import Your Localized Resources in v7.5

Import functionality has been delayed for several versions of DbLocalizationProvider. However, with the help of community member - this feature has...

valdis | Nov 21, 2022 | Syndicated blog

Optimizely CMS running on .NET 7!

Can you run Optimizely CMS on .NET 7? Yes! Can you upgrade in less than a day? Probably!

Tomas Hensrud Gulla | Nov 18, 2022 | Syndicated blog

Take experimentation velocity to the next level with Mutually Exclusive Experiments in Edge

The need for Mutually Exclusive Experiments in Edge When they visit our customers’ sites, Edge users are likely to see more than one related...

Thanh-Vi Le | Nov 15, 2022