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.
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 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
andEPiServer.Cms.AspNet
. EPiServer.MirroringService.MirroringMonitoring.MirroringMonitoringModule
has moved fromEPiServer.Enterprise
toEPiServer.Cms.AspNet
. It must be manually changed inweb.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 fromPropertyData
. UseIPropertyControlFactory
instead to register and create controls forPropertyData
types.- Providers (for example
ContentProvider
,BlobProvider
) no longer inheritProviderBase
. If a provider that supports configuration throughweb.config
has an initialization method with the signature voidInitialize(string name, NameValueCollection config)
, it will be called during the initialization phase IServiceLocator
no longer supports named instances. The specific implementation inEPiServer.ServiceLocation.StructureMap
supports named instances.- Some methods in
IServiceLocator
were removed from the interface and are now extension methods inEPiServer.ServiceLocation
namespace. EPiServer.Search.SearchSettings.Config
was replaced byEPiServer.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. UseIStringFragmentControlResolver
instead to create controls for string fragments. - Configuration sections
EPiServerFrameworkSection
,StaticFileSection
,EPiServerDataStoreSection
andSearchSection
were moved to assemblyEPiServer.Framework.AspNet
. - Property
Database
onDataAccessBase
was removed and is replaced by the propertyExecutor
. PageData.LinkUrl
no longer contains the query parameterepslanguage
.ContentProviders
can no longer useCacheSettings.Filenames
(previously obsoleted) to set up dependencies to files.EPiServer.Web.InitializationModule
was moved toEPiServer.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 moduleEPiServer.Initialization.CmsCoreInitialization
in assemblyEPiServer
. 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 assemblyEPiServer
were moved to extensions method defined in assemblyEPiServer.Cms.AspNet
. TypeUrlBuilder.RebaseKind
is also moved toEPiServer.Web.RebaseKind
inEPiServer.Cms.AspNet
assembly. AccessControlList.Save
was deprecated and is no longer supported. UseIContentSecurityRepository
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 anyIRenderTemplate
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 eachRawProperty
. Instead, this is done by calling theIPropertyExporter.ExportProperties
method.EPiServer.Core.Transfer.IPropertyImporter
has changed slightly to match the newIPropertyExporter
interface.PropertyData.ToRawString()
is no longer called when exporting data. If a CustomPropertyData
type had previously overridden theToRawValue
method, it must now move that functionality to a class that implementsIPropertyExportTransform
and register it with the Container.- PropertyJson-based properties, such as
PropertyList<T>
, no longer rely onIObjectSerializer
and container-registeredJsonConverters
for their serialization. They now useNewtonsoft.Json.JsonConvert
directly. This means thatJsonConverters
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 ofIVersionable.StartPublish
andIVersionable.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 toEPiServer.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 serviceIPropertyDataSettingsHelper
instead. SettingsContainer
is obsoleted. Use the extension methodGetSettingsContainer
or serviceIPropertyDataSettingsHelper
instead.TranslateDisplayName()
orTranslateDescription()
was moved toextension
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
andUIHint.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 theContentReference
of the moved content instead of void. This adds support for the scenario where content is assigned a newContentLink
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 methodResetPassword(IUIUser user, string newPassword)
instead. - CMS-8802 The deprecated
datetime.js
methodsserialize()
and `deserialize()' were removed. - CMS-8816 The deprecated slash method was removed from
epi/string
. - CMS-8817
epi-cms/widget/HierarchicalList
was replaced byepi-cms/asset/HierarchicalList
. - CMS-8830 The deprecated property
SiteDefinitionResolver
onContentSearchProviderBase
was removed. UseSiteResolver
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 fromException
. - The
UIHint.LongString
was obsoleted and should be replaced withUIHint.Textarea
. - Properties that use
LegacyPropertyEditorDescriptor
should be explicitly annotated withUIHint.Legacy
. - Obsoleted constructors are removed where there are public constructors available that can be used instead.
- Obsoleted properties were removed from
PropertyUpdateResult
,ComponentContainer
,ContentSearchProviderBase
, andCmsModuleViewModel
. - Obsoleted classes
ZipFileVirtualPathProvider
andSecurityEntityUtility
were removed. - Obsoleted methods were removed from
UIDescriptorRegistry
. _GrigWidgetBase
now emitsselectionChanged
when deselecting row. Previously, it was triggered only when a row was selected.- The obsoleted delegate
DependencyGetter
was removed. - The obsoleted methods
watchModelChange
andunwatchModelChange
inepi/shell/_Command
was changed from public to internal. - The class
ContentReferenceStore
that was available byepi.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
inweb.config
.
Updated 7 months ago