Upgrading to CMS 12

Recommended reading 
Note: This documentation is archived because it was the preview version of the release of CMS 12/Commerce 14/Search & Navigation 14. See Get started developing with CMS.

Optimizely CMS 12.0 is a major version that contains breaking changes to the API. However, upgrading to CMS 12.0 does not require a data migration, so upgrading is no different from installing feature updates through NuGet.

To ensure a smooth upgrade, see the following sections:

Breaking changes

A breaking change may cause a component to fail. When a breaking change is made to a signature of a method, class, or interface, the former signature is often kept intact but set as obsolete and may cause a warning message in Visual Studio. To delay fixing the warning messages, you can disable Treat Warnings as Errors [right-click on your project > Properties > Build > set Treat Warnings as Errors to Specific warnings or None].

Classes that expose constructors that take dependencies are normally deleted without an obsolete warning in major releases, because the compiler provides information about what you need to change. Keeping those classes makes dependency injection complex because, over time, there would be multiple constructors to choose from that might overlap.

In each major version, obsolete methods are removed permanently to make sure that the API is kept clean and usable. If you could postpone fixing warning messages, you should make sure warning messages are fixed before upgrading to a major version. For CMS 12.0, many methods that were made obsolete in prior versions are now deleted.

See Breaking changes for CMS 12.

Upgrading add-ons

You can upgrade add-ons with the platform in Visual Studio through NuGet.

Add-ons that are installed via the user interface must be converted to NuGet add-ons before upgrading to CMS 12. You can convert user interface add-ons to NuGet add-ons automatically through Visual Studio. See Linus Ekström's blog post Upgrading your site and add-ons to EPiServer CMS 8 pre-release for instructions.

You must disable incompatible user interface add-ons to reach the user interface and the update functionality. An exception message shows how to disable an add-on that blocks startup. See disabling add-ons and UI vs Visual Studio add-ons.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Jul 02, 2021

Recommended reading