Last updated: Nov 21 2017
Breaking changes in CMS 11
This topic describes breaking changes for Episerver CMS in relation to previous version 10, 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 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
Many APIs have moved to another NuGet package. Most 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.SearchSetting.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 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 EPiServer 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.
Ensure manually and automatically registered templates shares the same behavior (CMS-4161)
- Templates registered manually using ITemplateRepository.AddTemplates will now be 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 nows checks if an existing 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.
- 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.
Remove explicit IVersionable implementation on PageData (CMS-7700)
- PageData no longer exposes a separate explicit implementation of IVersionable.StartPublish and IVersionable.StopPublish.
Improve performance when loading large amount 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 should 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 should 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.
- CMS-7749 ProviderBasedLocalizationService.Providers is not thread safe.
- CMS-7791 Simple address router is the first registered one, and can be a waste on performance.
- CMS-6988 MoveContentEventArgs.ContentLink should be updated when content is moved between providers.
- CMS-1130 UIHints for block and media folders should be merged into an assets folder.
- CMS-1252 JsonErrorHandlingAttribute swallows exceptions and should be removed.
- CMS-6217 Content repository descriptor keys is case sensitive.
- CMS-6815 IContentChangeManager Move should return the new ContentReference.
- CMS-8229 ApplicationUIUserManager.ResetPassword(IUIUser user) should throw exception.
- CMS-8802 Remove deprecated serialize and deserialize methods in epi/datetime.
- CMS-8816 Remove deprecated slash method from epi/string.
- CMS-8817 Remove the deprecated epi-cms/widget/HierarchicalList.
- CMS-8830 Remove deprecated property on ContentSearchProviderBase.
- CMS-8832 Remove deprecated EPiServer.Shell.Web.Mvc.Html.DojoExtensions.
- CMS-9129 Not supported HostType's Service, Installer, VisualStudio should be 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"' and the type EPiServer.Security.WindowsMembershipProvider, EPiServer' to EPiServer.Security.WindowsMembershipProvider, EPiServer.Cms.AspNet in web.config.