HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

Upgrade to CMS 9

Optimizely Content Management System (CMS 9) is a major version containing some incompatible API changes.

There is no data migration required; updating to CMS 9 is no different from updating to the feature updates delivered previously via NuGet. To make sure the upgrade is as smooth as possible, there are a few steps that you may want to take that are discussed in the next sections.

Breaking changes, what are they and how to deal with them

A breaking change is a change that might cause other components to fail. When a breaking change is done to the signature of a method/class/interface, the old signature is often kept intact but set as obsolete and may cause a warning message in Visual Studio. As long as the Visual Studio project setting "Treat Warnings as Errors" is not enabled in Visual Studio, you can postpone fixing these warnings to a later time.

Classes that expose constructors that take dependencies are normally deleted without an obsolete warning in major releases, since the compiler gives enough information about what to change. Keeping them makes dependency injection complex since there are multiple constructors to choose from that, over time, might or might not overlap.

In each major version, old obsolete methods are removed permanently to make sure that the API is kept clean and usable over time, so even if you can postpone fixing warning messages, it is good practice to make sure all warning messages are fixed before upgrading to a major version. For CMS 9, many methods that were made obsolete in 8.0 are now deleted.

Note that EPiServer.CMS.Core no longer has a dependency on EPiServer.Logging.Log4Net. The NuGet package EPiServer.Logging.Log4Net may, because of this, be removed by NuGet when upgrading to CMS 9 (depending on version of NuGet and in which order the packages were installed). You need to manually ensure that the package is installed after upgrading to continue logging via Log4Net.

See Breaking changes in CMS 9

Upgrading add-ons

Add-ons managed via Visual Studio can be upgraded together with the platform via NuGet. Add-ons that are installed via the user interface have to be upgraded via the user interface.

It is recommended that add-ons that are installed via the user interface are converted to NuGet add-ons after the upgrade to CMS 9. A tool is available that can automatically convert add-ons that were previously managed via the user interface to be managed as NuGet packages via Visual Studio. For more instructions on how to convert user interface add-ons to NuGet add-ons, see Linus Ekström's blog post Upgrading your site and add-ons to EPiServer CMS 8 pre-release.

Incompatible add-ons installed via the user interface must be disabled to be able to reach the user interface and the update functionality. An exception message is shown with information on how to disable an add-on that blocks startup. You can read more about disabling add-ons and UI vs Visual Studio add-ons.