Dev GuideAPI ReferenceUser Guide
HomeDev GuideRecipesAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
Legal TermsGitHubNuGetDev CommunityOptimizely AcademySubmit a ticket

Breaking changes in CMS 11

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

Suggest Edits

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, described in this document.

New NuGet packages

In Optimizely Content Management System (CMS 11), some functionality, such as TinyMCE, was moved to separate NuGet packages. These packages have their own version number and may or may not be upgraded with the core CMS packages.

XForms has also been moved to its own NuGet package. This means that the Forms viewer gadget, which was deprecated in CMS 10, is now also removed.

Most upgrades do not require code changes but require a re-compilation. You should have the correct packages installed. A missing package causes compilation errors after upgrading a site. See New NuGet packages for which packages you must manually add.

Separate NuGet packages for ASP.NET dependencies (CMS-8106)

  • The integration with ASP.NET has moved to separate packages EPiServer.Framework.AspNet and EPiServer.Cms.AspNet.
  • EPiServer.MirroringService.MirroringMonitoring.MirroringMonitoringModule has moved from EPiServer.Enterprise to EPiServer.Cms.AspNet. It must be manually changed in web.config for the mirroring module.
  • Usage of StructureMap as IOC container was moved to a separate package, EPiServer.ServiceLocation.StructureMap.
  • .NET Framework 4.61 is required.
  • MVC 5.2.3 is required.
  • CreatePropertyControl was removed from PropertyData. Use IPropertyControlFactory instead to register and create controls for PropertyData types.
  • Providers (for example ContentProvider, BlobProvider) no longer inherit ProviderBase. If a provider that supports configuration through web.config has an initialization method with the signature void Initialize(string name, NameValueCollection config), it will be called during the initialization phase
  • IServiceLocator no longer supports named instances. The specific implementation in EPiServer.ServiceLocation.StructureMap supports named instances.
  • Some methods in IServiceLocator were removed from the interface and are now extension methods in EPiServer.ServiceLocation namespace.
  • EPiServer.Search.SearchSettings.Config was replaced by EPiServer.Search.SearchSettings.Options.
  • It is no longer supported to get an ILogger instance from IOC container.
  • Calls to logger that occur before IConfigurableModules are created, are not guaranteed to be persisted.
  • The setting for logger factories episerver:LoggerFactoryType must now always be quailfied with assembly name, even for built-in logger factories.
  • The method IStringFragment.GetControl was removed. Use IStringFragmentControlResolver instead to create controls for string fragments.
  • Configuration sections EPiServerFrameworkSection, StaticFileSection, EPiServerDataStoreSection and SearchSection were moved to assembly EPiServer.Framework.AspNet.
  • Property Database on DataAccessBase was removed and is replaced by the property Executor.
  • PageData.LinkUrl no longer contains the query parameter epslanguage.
  • ContentProviders can no longer use CacheSettings.Filenames (previously obsoleted) to set up dependencies to files.
  • EPiServer.Web.InitializationModule was moved to EPiServer.Cms.AspNet assembly and can be used as a dependency module for other modules that want to run after Optimizely CMS is initialized when running as an ASP.NET application. There is a new module EPiServer.Initialization.CmsCoreInitialization in assembly EPiServer. It can be a dependency module for modules that want to run after CMS Runtime is initialized when running CMS outside ASP.NET context.
  • Previously obsoleted methods Rebase/MakeRelative on type EPiServer.Web.UrlBuilder in assembly EPiServer were moved to extensions method defined in assembly EPiServer.Cms.AspNet. Type UrlBuilder.RebaseKind is also moved to EPiServer.Web.RebaseKind in EPiServer.Cms.AspNet assembly.
  • AccessControlList.Save was deprecated and is no longer supported. Use IContentSecurityRepository instead.

Manually and automatically registered templates share the same behavior (CMS-4161)

  • Templates registered manually using ITemplateRepository.AddTemplates are now associated with the model type for which they are added, rather than the model type indicated through any IRenderTemplate interface of the template. This may affect the template selection during runtime, as the model type association is used to decide which template to use when rendering a content item. This change does not affect automatically registered templates, as they are already registered using the type specified by the IRenderTemplate interface.
  • The default implementation of ITemplateRepository.AddTemplates now checks if a template exists before adding it. If the template is already registered, it does not add another one.
  • The default implementation of ITemplateRepository.AddTemplates now makes sure that all template models are read-only before adding them to the repository.

PropertList (CMS-7212)

  • EPiServer.Core.Transfer.IRawContentRetriever no longer populates the value of each RawProperty. Instead, this is done by calling the IPropertyExporter.ExportProperties method.
  • EPiServer.Core.Transfer.IPropertyImporter has changed slightly to match the new IPropertyExporter interface.
  • PropertyData.ToRawString() is no longer called when exporting data. If a Custom PropertyData type had previously overridden the ToRawValue method, it must now move that functionality to a class that implements IPropertyExportTransform and register it with the Container.
  • PropertyJson-based properties, such as PropertyList<T>, no longer rely on IObjectSerializer and container-registered JsonConverters for their serialization. They now use Newtonsoft.Json.JsonConvert directly. This means that JsonConverters must be defined as attributes on the classes and properties to which they apply.

Explicit IVersionable implementation on PageData is removed (CMS-7700)

  • PageData no longer exposes a separate explicit implementation of IVersionable.StartPublish and IVersionable.StopPublish.

Performance improved when loading large amounts of uncached content (CMS-7735)

  • CreateWritableClone is used to create content instances when loading from the database.

Target .NET Standard 2 in CMS.Core and Framework (CMS-8133)

  • ThumbnailManager was moved to EPiServer.Cms.AspNet.
  • Castle.Core dependency was changed to [4.2.1, 5.0).
  • Castle.Windsor dependency was changed from [4.1.0, 5.0).

Scheduled jobs have a shorter default content cache expiration (CMS-8653)

  • Content loaded from a database and added to cache by scheduled jobs has a shorter cache expiration (default 1 minute).

Memory usage optimization: Data class PropertyData does not expose services (CMS-8659)

  • SettingsID is obsoleted. Use extension method GetSettingsID or service IPropertyDataSettingsHelper instead.
  • SettingsContainer is obsoleted. Use the extension method GetSettingsContainer or service IPropertyDataSettingsHelper instead.
  • TranslateDisplayName() or TranslateDescription() was moved to extension method.

Other changes

CMS Core

  • CMS-7749 The Provider property is no longer supported, as it is impossible to expose a fully thread-safe IList implementation. 
  • CMS-7791 Simple address is now the last registered router.
  • CMS-6988 MoveContentEventArgs.ContentLink is updated when content is moved between providers.
  • CMS-9129 Unsupported HostType's Service, Installer, and VisualStudio were obsoleted.

CMS UI

  • CMS-1130 The UIHint.BlockFolder and UIHint.MediaFolder were obsoleted and are replaced by UIHint.AssetsFolder.
  • CMS-1252 Error message now displayed when updating partially rendered content.
  • CMS-6217 Content repository descriptor keys are now not case-sensitive.
  • CMS-6815 IContentChangeManager.Move(IContent source, IContent destination, bool createAsLocalAsset) now returns the ContentReference of the moved content instead of void. This adds support for the scenario where content is assigned a new ContentLink value when it is moved between different content providers.
  • CMS-8229 ApplicationUIUserManager<TUser>.ResetPassword(IUIUser user) now throws a not supported exception. This is because ASP.NET Identity does not support generating new passwords for security reasons. Use the new method ResetPassword(IUIUser user, string newPassword) instead.
  • CMS-8802 The deprecated datetime.js methods serialize() and `deserialize()' were removed.
  • CMS-8816 The deprecated slash method was removed from epi/string.
  • CMS-8817 epi-cms/widget/HierarchicalList was replaced by epi-cms/asset/HierarchicalList.
  • CMS-8830 The deprecated property SiteDefinitionResolver on ContentSearchProviderBase was removed. Use SiteResolver instead.
  • CMS-8832 The deprecated EPiServer.Shell.Web.Mvc.Html.DojoExtensions was removed, use .ConfigureDojo instead.
  • DateTime properties on the visitor group criterion model are serialized to ISO 8601 when being sent to the client.
  • The MissingConfigurationException now inherits directly from Exception.
  • The UIHint.LongString was obsoleted and should be replaced with UIHint.Textarea.
  • Properties that use LegacyPropertyEditorDescriptor should be explicitly annotated with UIHint.Legacy.
  • Obsoleted constructors are removed where there are public constructors available that can be used instead.
  • Obsoleted properties were removed from PropertyUpdateResult, ComponentContainer, ContentSearchProviderBase, and CmsModuleViewModel.
  • Obsoleted classes ZipFileVirtualPathProvider and SecurityEntityUtility were removed.
  • Obsoleted methods were removed from UIDescriptorRegistry.
  • _GrigWidgetBase now emits selectionChanged when deselecting row. Previously, it was triggered only when a row was selected.
  • The obsoleted delegate DependencyGetter was removed.
  • The obsoleted methods watchModelChange and unwatchModelChange in epi/shell/_Command was changed from public to internal.
  • The class ContentReferenceStore that was available by epi.cms.contentreferences key is now obsoleted.

Manual changes required to legacy feature Mirroring

An updated DLL is available in the EPiServer.CMS.Core NuGet package (packages/EPiServer.CMS.AspNet.11.1.0/tools/MirroringService/), which you must manually patch when upgrading.e

  • Change EPiServer.MirroringService.MirroringTransferProtocol.WCF.MirroringTransferClient,EPiServer.Enterprise 
    to
    EPiServer.MirroringService.MirroringTransferProtocol.WCF.MirroringTransferClient,EPiServer.Cms.AspNet 
  • Change the type EPiServer.Security.WindowsMembershipProvider,EPiServer 
    to 
    EPiServer.Security.WindowsMembershipProvider, EPiServer.Cms.AspNet in web.config.

Updated 10 months ago

Next