Speed-upgrading an add-on for Optimizely CMS 12 🚀

In order to upgrade your Optimizely CMS 11 site running on .NET Framework, to an Optimizely CMS 12 site running on .NET 5, all add-ons that you are currently using must be updated or removed.

Optimizely has a list of the status of their own add-ons and packages. If you are depending on an add-on that is not yet updated, you have several options.

• Break down and cry
• Ask the maintainer, politely
• Offer to help
• Postpone the upgrade

It doesn't HAVE to be too time consuming

Migrating to .NET 5 can be a lot of work, but if you're lucky it can be a matter of minutes!

An example

Exactly one year ago, I created an addon that writes the content of your Optimizely properties to the database with invisible ink. I will go through the steps involved in upgrading this very basic add-on. The fact that the add-on has no user interface, probably makes this a bit easier.

The steps

1. Install the tool

Upgrade Assistant is a dotnet tool from Microsoft that converts a .NET 4 codebase to a .NET 5 codebase. It is installed from the command line.

dotnet tool install -g upgrade-assistant

2. Run the tool

upgrade-assistant upgrade Gulla.Episerver.SuperSecretString.csproj

The tool will guide you through 8 steps.

1. Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
4. Update TFM
5. Update NuGet Packages
6. Add template files
7. Update source code
8. Move to next project

I don't need backup, so I'll skip the first step and save us a few seconds. And just speed through the steps from 2 to 8 as fast as possible, don't mind reading all the text.

3. Clean up the project file

Upgrade Assistant has converted the project file to the new minimalistic SDK format and taken the leap all the way to .NET 6. Let's go for .NET 5 for now.

I'll fire up Visual Studio and change the following line in the project file:

<TargetFramework>net6.0</TargetFramework>

to

<TargetFramework>net5.0</TargetFramework>

...and then remove every single item group. All of this needs to be gone. We'll add the EPiServer.CMS.Core dependency back later.

4. Delete some more stuff

Upgrade Assistant created a log file called upgrade-assistant.clef, we'll never look at that, so delete that file.

5. Add some stuff

To get things running, I'll need to add the NuGet package.

EPiServer.CMS.Core

I'll choose version 12.0.3, because David Knipe's best practice says I should always build my package against the lowest compatible version of Episer...cough...Optimizely!

6. Build it

========== Rebuild All: 1 succeeded, 0 failed, 0 skipped ==========

No problems here, let's move on...

7. Update the nuspec file

I'll update the nuspec file with a single updated dependency, following David Knipe's best practice, I'll keep it within a single major version.

<dependencies>
  <dependency id="EPiServer.CMS.Core" version="[12.0.3, 13.0.0)" />
</dependencies>

8. Pack it up

In 2022 you should probably(?) consider using msbuild when creating NuGet packages, but I don't have time for this if we're gonna finish in three minutes, so I'll just run nuget pack like we did last year, and the year before, and the year before...

9. Commit and upload

Just commit the changes to git, tag a new release, and upload the NuGet package to nuget.optimizely.com or nuget.org.

The upgraded addon is here on GitHub, and the NuGet package is available on nuget.org.