Upgrade Optimizely CMS From v11 to v12

Why Upgrade?

There are many improvements implemented in version 12, but most importantly is that the whole framework is migrated from .Net Framework 4 to .NET 6.

Upgrade also contains significant security, performance and headless improvements, while Optimizely framework APIs remains the same so existing code won't break and there is no DB migration involved, except for user tables which need to migrate from AspNet Identity scheme to OpenId.

Since it is now .Net Core native that also means it is OS agnostic and can be hosted on platforms other than Windows, like Linux for example.

How To Upgrade?

Suggested way is to use Optimizely Upgrade Assistant that will backup current solution and upgrade project to desired .NET Core version. The assistant will also try to migrate backend code and views, but that should be taken with caution. Developer needs to manually migrate from web.config to appsettings.json settings style, migration from global.asax to startup.cs, migration from OWIN and ASP.NET authentication to OpenID authentication, migration of block controllers to components, dependency injection, logging, JSON serialization etc.

WebForms are no longer supported, which means MVC is the preferred way to render content.

Upgrading from .Net Framework 4 to .NET 6 means that some of the NuGet packages used are no longer compatible and need either updating them to their .Net Core versions (and hoping they have compatible APIs) or replacing them with other packages or even rewriting some of the functionalities. That can't be predicted as every solution is specific and must be carefully analyzed before giving any estimations.

Most importantly, take backups of both solution and DB before taking any actions. Prepare a new environment for testing of upgraded solution where all functionalities can be checked before replacing the old solution.

Step By Step Guide

I have tested Optimizely Upgrade Assistant on a simple project with few page types and blocks.

First step is to install Assistant using .NET CLI tool by running command from Command Prompt:

dotnet tool install -g upgrade-assistant

This will install Microsoft Upgrade assistant from .Net Framework to .NET Core.

Second step is to download Optimizely extension from Upgrade Assistant GitHub: https://github.com/episerver/upgrade-assistant-extensions/releases

Unpack files into temporary folder like: C:\Temp\EPi.Source.Updater.1.0.33

Then, run the command to upgrade startup project:

upgrade-assistant upgrade {projectName}.csproj --extension C:\Temp\EPi.Source.Updater.1.0.33 --ignore-unsupported-features

After completing upgrade procedure you’ll end up with lot of dependency issues (both old Episerver packages and new ones mixed), unresolved code issues, project not structured up to .Net Core standards (no wwwroot folder, static files are still in the project root), Program.cs and Startup.cs need adjustments, code from Global.asax.cs not migrated…

So, there is a lot of work to do for such a small project. Alternatively, instead of running upgrade assistant, I would start by creating a new solution with empty Optimizely CMS project based on .NET 6 (using Optimizely Visual Studio project template). Then, gradually transfer code from the old solution to the new one. Copy static files to wwwroot folder, copy backend files. Install missing NuGet packages but with their .Net Core versions. Some packages will have different APIs so you’ll need to update method signatures, or even rewrite some portions of code completely if the method is no longer supported.

Keep in mind that .Net Core have a different dependency injection mechanism, logging, exception filters, JSON handling, block controllers are now components etc.

There is no magic wand for this process and must be done manually. At the end, after the project is successfully building, migrate DB users using script located in EPi.Source.Updater.1.0.33 folder.

Should I Upgrade?

That decision needs to be taken by answering some questions:

do I plan further development of current solution? If yes, then you should consider upgrading
am I satisfied with the performance of the current solution? If not, then you should consider upgrading
is investment in upgrading going to bring considerable value to the company? If yes, then you should consider upgrading