Dev GuideAPI ReferenceUser Guide
HomeDev GuideRecipesAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
GitHubNuGetDev CommunityOptimizely AcademySubmit a ticket
Start typing to search…

UI, editors, and shell breaking changes

Breaking changes to platform navigation, editor descriptors, TinyMce, shell modules, menu system, DAM integration, and admin UI in CMS 13.

This article covers CMS UI, editor descriptor, TinyMce, shell module, navigation menu, DAM integration, and admin area breaking changes in CMS 13.

Platform navigation

TagHelpers replace the HtmlHelper-based platform navigation.

  • EPiServer.Shell.Navigation.MenuHelper.CreatePlatformNavigationMenu – Converted from an HtmlHelper to a TagHelper. To render platform navigation on a custom view, use:

    <platform-navigation />

    Page content needs its height adjusted by another tag helper:

    <platform-navigation-wrapper>CONTENT</platform-navigation-wrapper>

  • EPiServer.Shell.Navigation.MenuHelper – The following methods were removed: LocalMenu, ShellMenu, EnsureValidMenuPath, CalculatePathDepth, CreatePlatformNavigationMenu, ApplyPlatformNavigation, CreateLocalMenu. Refer to PlatformNavigationTagHelper instead.

  • EPiServer.Shell.Navigation.MenuHelper – Field GlobalHeaderOptions was removed. Update options through the service container.

Shell module changes

  • EPiServer.Shell.ShellInitialization – No longer implements IConfigurableModule. Services are now registered using the AddCmsShell() service registration method.

  • EPiServer.Shell.UI.InitializationModule – No longer implements IConfigurableModule. Services are now registered using the AddCmsShellUI() service registration method. Method Preload was removed.

  • EPiServer.Shell.Modules.ShellModule – Previous constructors were removed. Only the default constructor is now exposed. Properties Name, RouteBasePath, ResourceBasePath and other dependencies are assigned through property injection by IModuleFinder. Classes inheriting ShellModule can no longer use these properties in their constructor. They can now inject service dependencies instead. Previously obsoleted method ResolveClientPath was removed.

  • EPiServer.Shell.Modules.ShellModuleItem – Field Dependencies was converted into a property and changed to type IList<AssemblyItem>.

  • EPiServer.Shell.Modules.AssemblyItem – Field Dependencies was converted into a property and changed to type IList<AssemblyItem>.

  • EPiServer.Shell.Modules.ModuleRouteConstants – Field RouteController changed from a static field to a const.

  • EPiServer.Shell.ShellModuleStaticFilesRegistration – Field _modulesPath was incorrectly made public and is now private as intended.

  • EPiServer.Shell.Modules.IContentExtensions – Method PreviewUrl was removed. Method ThumbnailUrl was removed. Parameter templateResolver was removed from method GetIcon.

Editor descriptors

Multiple editor descriptors had their constructors changed. The common pattern is:

  • Overloaded constructors were removed.
  • Constructor argument changed from IEnumerable<IContentRepositoryDescriptor> to IContentRepositoryDescriptorRegistry.
  • New constructor parameters IApplicationResolver and ServiceAccessor<SystemDefinition> were added.

Affected editor descriptors:

  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.ContentReferenceEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.ContentReferenceListEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.UrlEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.ImageUrlEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.MediaUrlEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.VideoUrlEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.LinkCollectionEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.LinkItemEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.PageReferenceListEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.ContentAreaEditorDescriptor
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.ItemCollectionEditorDescriptor

Selection factories

  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.SelectionFactories.PageTypeSelectionFactory – New constructor parameter LocalizationService.
  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.SelectionFactories.PropertySelectionFactory – New constructor parameters IContentTypeRepository and LocalizationService.

ClientEditorAttribute

  • EPiServer.Shell.ObjectEditing.ClientEditorAttribute – Now requires a stricter format for the EditorConfiguration field due to the switch to System.Text.Json. JSON object property names (RFC 8259) must be double-quoted strings. Single quotes or unquoted keys are invalid.

Removed editor types

  • EPiServer.Shell.ObjectEditing.EditorDescriptors.TextareaEditorDescriptor – Previously obsoleted class was removed.
  • EPiServer.Shell.ObjectEditing.ExtendedMetadata – Previously obsoleted property DefaultValue was removed.

TinyMce

  • EPiServer.Cms.TinyMce.Core – Method AddSettingsTransform throws an exception when name of the transform is null or empty. There is a new overload of AddSettingsTransform that accepts only a delegate and uses a generated name for the transform.

  • EPiServer.Cms.TinyMce.ServiceCollectionExtensions – Extension methods AddTinyMce() and DisableEditorValidation() moved to EPiServer.DependencyInjection namespace.

  • EPiServer.Cms.TinyMce.SpellChecker.ServiceCollectionExtensions – Extension method AddTinyMceSpellChecker() moved to EPiServer.DependencyInjection namespace.

Search providers

  • EPiServer.Cms.Shell.Search.ContentSearchProviderBase<TContentData, TContentType> – Parameter templateResolver was removed from ContentSearchProviderBase. Fields ContentTypeRepository, LanguageResolver, and EditPath were converted to properties. Constructor argument changed from ISiteDefinitionResolver to IApplicationResolver.

  • EPiServer.Shell.Search.SearchProvidersManager – Constructor takes a list of ISearchProviderSource instead of ISearchProvider. SearchProvidersManager is now internal. Use the ISearchProvidersManager abstraction instead.

  • EPiServer.Shell.UI.Rest.SearchResultStore – Made internal.

Menu and navigation system

  • EPiServer.Shell.Navigation.MenuAssembler – Now internal. To register a custom MenuItem, implement either IMenuProvider or IAsyncMenuProvider.

  • EPiServer.Shell.Navigation.MenuBuilder – Removed (leftover from WebForms).

  • EPiServer.Shell.Navigation.MenuItem – Removed unused Render method. The whole menu is now a React component.

  • EPiServer.Shell.UI.ShellMenuProvider – Removed (considered internal). Previously obsoleted property UserGuideUrl was removed.

  • EPiServer.Cms.UI.Settings.SettingsMenuProvider – Removed.

  • EPiServer.Shell.UI.FallbackModuleController – Removed (considered internal).

REST and context services

  • EPiServer.Shell.UI.Rest.ContextStore – The Get method renamed to GetAsync and returns Task<RestResultBase> instead of RestResultBase.

  • EPiServer.Shell.Rest.IUriContextResolver – The TryResolveUri method signature changed from bool TryResolveUri(Uri uri, out ClientContextBase instance) to Task<ContextResolutionResult> TryResolveUriAsync(Uri uri, CancellationToken cancellationToken = default).

  • EPiServer.Shell.Rest.IUrlContextResolver – The TryResolveUrl method signature changed from bool TryResolveUrl(Uri url, out ClientContextBase instance) to Task<ContextResolutionResult> TryResolveUrlAsync(Uri url, CancellationToken cancellationToken = default).

  • EPiServer.Cms.Shell.UI.Rest.ContentQuery – Removed constructors that do not accept UserInterfaceOptions, ContentTypeResolver, and IHasChildrenEvaluator arguments.

  • EPiServer.Cms.Shell.UI.Rest.GetPagedChildrenQuery – Constructor accepts a new argument IEnumerable<IHasChildrenEvaluator> hasChildrenEvaluators.

  • EPiServer.Cms.Shell.UI.Rest.IContentChangeManager – Interface aligned with ContentChangeManager.

  • EPiServer.Cms.Shell.UI.Rest.ContentChangeManager – Implementation moved to internal namespace since there is an interface IContentChangeManager.

Removed REST types

  • EPiServer.Shell.Services.Rest.RestResult – Previously obsoleted property StatusCode and constructor were removed.
  • EPiServer.Shell.Services.Rest.RestResultBase – Previously obsoleted property SafeResponse and constructor were removed.
  • EPiServer.Shell.Services.Rest.RestStatusCodeResult – Previously obsoleted constructor was removed.

Admin UI

  • EPiServer.Cms.UI.Admin.SectionsVisibility – PluginManager has been defaulted to false.

  • EPiServer.Cms.UI.Admin.AdminModule – New constructor parameter IContentIndexerProvider.

  • EPiServer.Cms.UI.Admin.ServiceCollectionExtensions – Extension method AddAdmin() moved to EPiServer.DependencyInjection namespace.

CMS Shell

  • EPiServer.Cms.Shell.ServiceCollectionExtensions – Extension methods AddCmsUI() and AddAdminUserRegistration() moved to EPiServer.DependencyInjection namespace.

  • EPiServer.Cms.Shell.SiteConfigurationRepositoryExtensions – Obsoleted class removed.

  • EPiServer.Cms.Shell.Extensions.SettingsExtensions – Previously obsoleted class removed.

  • EPiServer.Cms.Shell.LinkableTypesAssembler – Changed constructor argument from IEnumerable<IContentRepositoryDescriptor> to IContentRepositoryDescriptorRegistry.

  • EPiServer.Cms.Shell.CmsModule – One constructor removed, another simplified with unused parameters removed.

DAM integration

  • EPiServer.Cms.DamIntegration.UI.PropertyAttributeTagHelper – Can now render DAM assets with normal <img>, <video>, <a> tags when value contains a DAM asset ContentReference. CMS 12 used a TagHelper with a <dam-asset> tag to render DAM assets. DAM HtmlHelpers ported from CMS 12 in DamHtmlHelpers are obsolete.
  • DAM integration C# packages and NuGet references have moved from the EPiServer namespace to the Optimizely namespace. Update any using statements or package references from EPiServer.Cms.DamIntegration to Optimizely.Cms.DamIntegration accordingly.

Visitor Groups UI

  • EPiServer.Cms.UI.VisitorGroups.Api.ModelBinding.VisitorGroupContractResolver – Removed.

UI culture behavior

  • EPiServer.Cms.Shell.UI.Profile.CurrentUiCulture – UI language determination behavior changed when UICultureLanguageCode=auto or UseBrowserLanguagePreferences=true. The system now correctly reads the browser's language preference instead of defaulting to English. If no valid browser language is found, it falls back to English. Sites relying on the previous behavior where UICultureLanguageCode=auto did not apply browser language preferences may need to update their globalization configuration.

Other removed types

  • EPiServer.Shell.IUIDescriptorInitializer – Previously obsoleted interface removed.
  • EPiServer.Shell.Composition.IContainer – Previously obsoleted interface removed.
  • EPiServer.Shell.Web.Mvc.BootstrapperViewModel – Previously obsoleted properties GlobalNavigationMenuType and UseContainers removed.
  • EPiServer.Shell.Web.Mvc.DojoResourceResult – Previously obsoleted constructor removed.
  • EPiServer.Shell.Web.Mvc.JsonDataResult – Previously obsoleted constructors, property Serializer, and method WriteDataToResponse removed.
  • EPiServer.Shell.Web.Mvc.JsonExtensions – Class removed after the only method JsonData was removed.
  • EPiServer.Shell.Web.Mvc.WrappedJsonDataResults – Previously obsoleted constructor removed.
  • EPiServer.Shell.UIDescriptor – Previously obsoleted properties ContainerTypeIdentifier and MainWidgetType removed.
  • EPiServer.Shell.Web.GlobalNavigationMenuType – Previously obsoleted enum removed.
  • EPiServer.Shell.Web.ICustomGlobalNavigationMenuBehavior – Previously obsoleted interface removed.
  • EPiServer.Web.Mvc.Html.QuickNavigatorHtmlHelperExtensions – Previously obsoleted method RenderEPiServerQuickNavigator removed.
  • EPiServer.Shell.Security – Previously obsoleted synchronous methods in UIRoleProvider, UISignInManager, UIUserManager, and UIUserProvider removed.

CMS controllers

Controllers that inherit EPiServer.Cms.Shell.UI.Controllers.Internal.BaseController or EPiServer.Shell.Services.Rest.RestControllerBase and reside in Internal namespaces have changed access modifier from public to internal.

ContentDataStoreModel access changes

EPiServer.Cms.Shell.UI.Rest.Internal.ContentDataStoreModel and related model classes have changed from public to internal. Since REST controllers in EPiServer.Cms.Shell.UI are now internal, the models used by those controllers are also internal. Code that directly references these public model classes must be updated to use supported public APIs instead.

Removed shared views and JavaScript

  • Removed /CmsUIViews/Views/Shared/_Sleek.cshtml – This shared view was merged with /CmsUIViews/Views/Bootstrapper/Bootstrapper.cshtml.
  • Removed epi.resources JavaScript object – Load resources directly via "epi/i18n!epi/shell/ui/nls/episerver.shared" in the dependency list of define.

Removed editor descriptors and helpers

  • EPiServer.Cms.Shell.PageInfoHelper – Class removed. Was previously obsoleted.

  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.PropertyValueList.PropertyValueListEditorDescriptor<T> – Abstract base class removed, along with all concrete implementations: PropertyDateTimeListEditorDescriptor, PropertyDoubleListEditorDescriptor, PropertyIntListEditorDescriptor, and PropertyStringListEditorDescriptor. Logic has been moved to PropertyCollectionMetadataExtender.

  • EPiServer.Cms.Shell.UI.ObjectEditing.EditorDescriptors.ImageReferenceEditorDescriptor – Parameterless constructor (using ServiceLocator) removed. Use the constructor with an explicit FileExtensionsResolver dependency.

  • EPiServer.Cms.Shell.UI.Rest.Models.PatchContentDataModel – Properties ForceCurrent and PublishChanges removed. Use the Action property instead.

  • EPiServer.UI.Shell.UiWrapperType – Constant Inline removed. Use ContentEditable instead.

EPiServer.Cms.AspNetCore.HtmlHelpers

  • EPiServer.Web.Mvc.Html.PageHtmlHelperExtensions – Three PageLink overloads accepting IContentRepository were removed. Use Html.ContentLink instead.

  • EPiServer.Web.Mvc.Html.PropertyExtensions – Static property CustomSettingsAttributeWriter removed. Use PropertyRenderer.CustomSettingsAttributeWriter instead.

  • EPiServer.Web.Mvc.Html.ContentAreaRenderer – Protected method ResolveTemplate(IHtmlHelper, ...) removed. Use ResolveContentTemplate instead. Protected method IsInEditMode(IHtmlHelper) removed. Use IsInEditMode() without parameters instead.

  • EPiServer.Web.Mvc.PartialRequest – Class removed. Use IContentRenderer to render content items, or Html.RenderPartial/Html.RenderPartialAsync to render partial views.

EPiServer.Cms.AspNetCore.Templating

  • EPiServer.Editor.PageEditing – Property PageIsInEditMode was removed. Constant DataEPiUseMvc was removed.

  • EPiServer.Framework.Web.TemplateTypeCategories – WebForms-related enum values removed: WebFormsPage, ServerControl, and WebFormsPartial. The composite value Request retains its numeric value for binary compatibility.

  • EPiServer.Framework.DataAnnotations.TemplateDescriptorAttribute – Property Default removed. It is no longer possible to register a template as default.

  • EPiServer.Web.RenderSettings – Constants CustomTag and ChildrenCustomTag removed. Use CustomTagName and ChildrenCustomTagName instead.

  • EPiServer.Web.TemplateResolverExtensions – All 8 obsolete extension methods removed:

    • ResolveMvcTemplate (4 overloads) – Use ResolveTemplate() instead.
    • ResolvePageTemplate (4 overloads) – Use ResolveRequestTemplates() instead.

  • EPiServer.VisitorGroupsCriteriaPack.DisplayChannelModel – Parameter currentGroup was removed from method Validate(VisitorGroup currentGroup).

  • EPiServer.Web.EditContainer – Parameter useMvc was removed from its constructor.

EPiServer.Cms.AspNetCore

  • EPiServer.Web.MediaOptions – The DefaultContentType field was changed to a property.

  • EPiServer.VisitorGroupsCriteriaPack.EventCriterion – The _currentTimeProvider field was removed.

  • EPiServer.Personalization.VisitorGroups.SessionStartCookieCriterionBase – The protected _validCookieKey field was replaced with ValidCookieKey property.

EPiServer.Cms.AspNetCore.Mvc

  • EPiServer.Web.Mvc.BlockController – Obsolete class removed.
  • EPiServer.Web.Mvc.ContentAreaContext – Obsolete class removed.
  • EPiServer.Web.Mvc.ContentContext – Obsolete class removed.
  • EPiServer.Web.Mvc.PartialContentController – Obsolete class removed.

EPiServer.UI

  • EPiServer.UI.Edit.ImageEditor.ImageSaveEvents – Field OnImageSave converted into a property.

ValidateAntiForgeryReleaseToken

  • Removed unintentionally exposed internal attribute. Replace with Microsoft.AspNetCore.Mvc.ValidateAntiForgeryTokenAttribute.

AcceptAntiforgeryTokenFromQueryAttribute

  • EPiServer.Cms.Shell.UI.Attributes.AcceptAntiforgeryTokenFromQueryAttribute - Removed. Controllers decorated with this attribute must be rewritten to handle tokens passed via header instead.

Updated 1 day ago