HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Breaking changes in CMS 10

This topic describes breaking changes for Optimizely Content Management System (CMS 10) in relation to previous version 9, and the steps needed to update affected code.

To view the complete list of changes, see the release notes feed.

Some changes are binary breaking but do not necessarily require code changes but rather a project recompilation. Breaking changes are changes in method signatures or behavior of methods compared to the documented API in the previous version, which is described in this document.

The new ".Internal" namespaces

One of the bigger changes is that all APIs were reviewed to find internal implementation classes and that those were moved to internal namespaces. You can see exactly which APIs are affected in these stories: CMS-3762 (Episerver CMS Core) and CMS-3755 (Episerver CMS UI). Read more about these changes in Henrik Nyström's blog post.

Event system

The event system (used primarily for communication between instances in a load-balanced environment) will no longer guarantee that events are processed sequentially, one at a time. Code that uses the event system should be reviewed for thread safety and cannot rely on the order in which events arrive to the event listener.
Implementors of custom event providers should also be aware that SendMessage calls are no longer guaranteed to run in a separate thread and should therefore take precautions to ensure optimal performance.

Remove support for legacy dot notation for dojo modules

Optimizely is removing the support for the legacy dot notation for dojo modules, for example, epi-cms.editing.ContentPicker. This means that you need to change all EditorDescriptors, Components and so on where you have defined your Dojo modules using the . to /. Read more CMS-2295 and in Ben McKernan's blog post.

EPiServer.Shell moved to EPiServer.CMS.UI.Core

EPiServer.Shell.dll was moved from NuGet package EPiServer.Framework to EPiServer.CMS.UI.Core. If you have both packages installed, no change is required. Read more in CMS-1380.



If you get an error message saying Value cannot be null.Parameter name: virtualPath]in EPiServer.Shell.ShellInitialization.WaitForInitializeModules()..., remove the EPiServer.Shell.dll from the site bin folder. This may happen for sites that do not have the EPiServer.CMS.UI.Core installed, for example Commerce Manager.

Converting the database to UTC is a required step

Running the database with local date and time will no longer be supported (CMS-1449). A database not converted to UTC will throw an exception to avoid data loss caused by mixing local and UTC date and time. Conversion can be done before upgrading for versions 9.1 or later, for example, using the provided PowerShell scripts, see Storing UTC date and time in the database for more details. A setting can be added to the appSettings section of web.config to disable the exception if the site temporarily have to be started without doing the conversion, add episerver:DisableDateTimeKindValidation with value true.

More breaking changes in UI:

  • CMS-4925 Objects of type epi._Dependency can no longer be created
  • CMS-1202 GetContentByPermanentLinkQuery will always return the content without work id
  • CMS-2710 Dialog now has destroyOnHide:true by default
  • CMS-4319 The value of enum ExtendedVersionStatus.Expired have changed
  • CMS-1150 Calling watchModelChange and unwatchModelChange on _Command.js has been deprecated

More breaking changes in Core:

  • CMS-4110 The event args in the post event MovedContent will now contain the content loaded after the move
  • CMS-3852 ContentStore methods for saving data has been removed
  • CMS-3756 IAvailableModelSettingsRepository method signature changes
  • CMS-3763 ContentScannerExtension method signature changes
  • CMS-3166 ContentSearchHandler changed to an abstract class
  • CMS-3131 LocalizationService now returns fallback language before fallback defined in code
  • CMS-1197 LanguageBranch now implements IReadOnly and LanguageBranch.URLSegment will now return the LanguageID if not set to a custom value
  • CMS-1320 Browsing to expired page will now return a 404
  • CMS-1266 No longer allowed to have the wildcard host as the only host for any given language
  • CMS-2078 Align status transitions, events and required access rights when saving
  • CMS-3824 UrlSegment have been replaced with IUrlSegmentCreator/IUrlSegmentLocator/IUrlSegmentGenerator
  • CMS-3823 SiteDefinitionRepository and SiteDefinitionResolver have been replaced with ISiteDefinitionRepository and ISiteDefinitionResolver
  • CMS-3090 Added validation of virtual content type properties defined on interfaces
  • CMS-3153 IContentVersionRepository List methods have been consolidated into one. PageVersion is obsoleted.
  • CMS-3449 PropertyResolver changed to an abstract class
  • CMS-3530 New method ImportProperties introduced on IContentTransfer
  • CMS-3591 HostDefinitionExtensions.FirstOfType return wildcard host last
  • CMS-3764 AdministrationSettingsService is replaced with IAdministrationSettingsService
  • CMS-3854 Extended IContentEvents with events RequestingApproval and RequestedApproval
  • CMS-3859 Create a language branch of a non-localized content should not be possible
  • CMS-3860 GetDefault when content implements ILocale but now ILocalizable will not set language
  • CMS-1206 IContentVersionRepository.Delete method will now throw an exception when a version cannot be deleted
  • CMS-3982 New event ContentSecuritySaving added to IContentSecurityRepository
  • CMS-3983 Event args type changed on ContentLanguageSettingRepository
  • CMS-3987 PropertyDate.Date/PageData.StartPublish/PageData.StopPublish are now nullable
  • CMS-4167 ContentCoreData.StartPublish/StopPublish properties are now nullable
  • CMS-3812 Empty properties were changed to work more like standard .NET properties
  • CMS-3991 Methods removed from IPermanentLinkMapper
  • CMS-4149 Experimental setting UseLegacyValueType from EPiServer 7 to return legacy value types has been removed
  • CMS-2807 ContentLanguageSettings were replaced with IContentLanguageSettings and ContentLanguageSettingsResolver
  • CMS-4445 Delay publish job is now impersonating the user that scheduled the publish
  • CMS-4537 IScheduledJobStatusService.ReportExecutedJob method signature changed
  • CMS-4219 PropertyLinkCollection no longer inherits PropertyXhtmlString. It is now a direct base class to PropertyLongString.