Navigating the .NET Core Upgrade for Optimizely CMS 12

Every upgrade comes with its own challenges, and the first time you implement a new upgrade, there are bound to be a few surprises. We recently finished upgrading an Optimizely website from .NET Framework to .NET Core. This particular upgrade was needed to move the website to Optimizely CMS 12, which is not compatible with .NET Framework.  

Both Microsoft and Optimizely have tools to aid with the upgrade. Here’s what we encountered while using them. 

Start with Microsoft’s Upgrade Assistant 

Microsoft provides their Upgrade Assistant to help you get started. Developers should use the analyzer function of the tool first to get a big picture understanding of what changes may be required, such as packages that need to be upgraded/removed or any incompatibilities with .NET Core.  As the tool goes through the projects in the solution, it will also alert you to any references to the System.Web namespace that will potentially require a good amount of work to reconcile. 

We found that the upgrade assistant works very well for class library projects that contain mostly business logic (i.e. model classes, helpers, etc.) with little or no web-based aspects.  In contrast, our web project had some rather big hurdles to overcome. In particular, Microsoft removed the System.Web namespace, with the exception of some utility classes. This was the backbone of ASP.NET MVC projects, so you can imagine how many updates were needed to get things running again. 

As part of the initial analysis, before the tool starts making actual updates to files, it may suggest skipping the web project. If it does, we suggest instructing it to include the project. The upgrade assistant will take care of some of the simple changes, like updating namespaces for classes that migrated over or adding an HttpContextHelper class to help access the current context. However, many items will be left to be updated manually.  After the tool has completed the initial updates, be prepared to have a web project that is in a broken state. The number of leftover changes will vary greatly from project to project and depend on a lot of factors like the use of request lifecycle logic or if you want to take advantage of .NET Core’s built in Dependency Injection framework. 

Add in the Optimizely Extension 

Optimizely created an extension to Microsoft’s Upgrade Assistant that will add Optimizely-specific steps to the upgrade process. It will make a number of changes in your web project. For example, Optimizely changed their block controller name from “BlockController” to “BlockComponent” to more closely match ASP.NET core ViewComponent naming convention, and the extension will make that change for you. It will also update your Startup and Program files to include Optimizely specific configuration. 

One thing to keep an eye on when using the Optimizely extension for the upgrade assistant is that it may try to add files like Startup.cs and Program.cs to every project. You can skip these steps when running in interactive mode and this will keep you from having to do any unnecessary clean up after the tool has completed. 

Take the Interactive Option 

Together, the upgrade assistant with the Optimizely extension will do a very good job making updates to your standard class library and web-based projects. When you start, you’ll be given the choice to run the upgrade assistant interactively or non-interactively. Microsoft recommends that you run interactively, and I agree. If you do opt for the non-interactive option, you will not have the ability to skip any steps that are not required. You may also miss messages that detail any additional updates that may be required that the tool was not able to do. 

As with most choices, there is a drawback to running in interactive mode. Namely, you’ll have to sit with the tool and instruct it to complete or skip each step. Some projects may only take 10-20 minutes to complete. Some may take up to a couple hours. However, you are going to have complete control over what gets updated, know what changes were made, and see all the messages the tool outputs that will help you complete any remaining issues. For our upgrade, this was definitely worth it. 

We certainly learned a lot from our first upgrade to .NET Core for Optimizely CMS 12. And learning from what we experienced will help the next ones go even more smoothly.  

Interested in getting started? Contact us today!