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

Breaking changes in CMS 11

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 just a recompilation of the project. Breaking changes are changes in method signatures or behavior of methods compared to the documented API in the previous version, which are described in this document.

New NuGet packages

In Optimizely Content Management System (CMS) version 11, some functionality, as for example TinyMCE, has been moved to separate NuGet packages. These packages have their own version number and may or may not be upgraded together 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 changes to code but require a re-compilation. It is important to have the correct packages installed. A missing package causes compilation errors after upgrading a site. See New NuGet packages for which packages you need to 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 has been 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 have been removed from interface and are now extension methods in EPiServer.ServiceLocation namespace.
  • EPiServer.Search.SearchSettings.Config has been 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 has been removed. Use IStringFragmentControlResolver instead to create controls for string fragments.
  • Configuration sections EPiServerFrameworkSection, StaticFileSection, EPiServerDataStoreSection, and SearchSection have been moved to assembly EPiServer.Framework.AspNet.
  • Property Database on DataAccessBase has been 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 has been moved to EPiServer.Cms.AspNet assembly and can be used as dependency module for other modules that want to run after Optimizely CMS is initialized when running as a ASP.NET application. There is a new module EPiServer.Initialization.CmsCoreInitialization in assembly EPiServer. It can be used as 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 have been 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 has been 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 new instances of content instances when loading from database.

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

  • ThumbnailManager has been moved to EPiServer.Cms.AspNet.
  • Castle.Core dependency has been changed to [4.2.1, 5.0).
  • Castle.Windsor dependency has been 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()/TranslateDescription() was moved to extension method.

Other changes

CMS Core

  • CMS-7749 The Provider property is no longer supported, as it is not possible 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, VisualStudio have been obsoleted.

CMS UI

  • CMS-1130 The UIHint.BlockFolder and UIHint.MediaFolder have been 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 due to the fact that 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() have been removed.
  • CMS-8816 The deprecated slash method has been removed from epi/string.
  • CMS-8817 epi-cms/widget/HierarchicalList has been replaced by epi-cms/asset/HierarchicalList.
  • CMS-8830 The deprecated property SiteDefinitionResolver on ContentSearchProviderBase has been removed. Use SiteResolver instead.
  • CMS-8832 The deprecated EPiServer.Shell.Web.Mvc.Html.DojoExtensions has been 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 has been obsoleted and should be replaced with UIHint.Textarea.
  • Properties which 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 have been removed from PropertyUpdateResult, ComponentContainer, ContentSearchProviderBase, and CmsModuleViewModel.
  • Obsoleted classes ZipFileVirtualPathProvider and SecurityEntityUtility have been removed.
  • Obsoleted methods have been removed from UIDescriptorRegistry.
  • _GrigWidgetBase now emits selectionChanged when deselecting row. Previously, it was triggered only when a row was selected.
  • The obsoleted delegate DependencyGetter has been removed.
  • The obsoleted methods watchModelChange and unwatchModelChange in epi/shell/_Command has been 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.

Change

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

Updated 5 months ago