Sites-to-applications and routing breaking changes
This article covers SiteDefinition-to-Application migration, URL routing, and UriSupport replacement breaking changes in CMS 13.
Sites-to-applications migration
CMS 13 replaces the SiteDefinition model with a new Application model. The following types are obsoleted:
- EPiServer.Web.SiteDefinition – Obsolete in favor of Application.
- EPiServer.Web.SiteDefinitionEventArgs – Obsolete in favor of ApplicationEvent.
- EPiServer.Web.SiteDefinitionUpdatedEventArgs – Obsolete in favor of ApplicationUpdatedEvent.
- EPiServer.Web.ISiteDefinitionRepository – Obsolete in favor of IApplicationRepository. A temporary shim layer loads applications as site definitions during the transition.
- EPiServer.Web.ISiteDefinitionResolver – Obsolete in favor of IApplicationResolver.
- EPiServer.DataAbstraction.ISiteConfigurationRepository – No longer used by CMS and obsoleted. No implementation is registered.
Host configuration changes
- Wildcard site host definition (*) is replaced with a default application. The Application.IsDefault property controls this behavior.
- Database migration preserves existing sites, but the application model requires explicit "Default" host configuration. You may need to configure this manually in Admin > Config > Manage Applications. See Application framework to understand available application types.
Constructor and parameter changes
When upgrading code that depends on SiteDefinition or ISiteDefinitionResolver:
- Replace ISiteDefinitionResolver with IApplicationResolver in constructor injection.
- EPiServer.Cms.Shell.Search.ContentSearchProviderBase<TContentData, TContentType> – Changed constructor argument from ISiteDefinitionResolver to IApplicationResolver.
- EPiServer.Web.Routing.EditUrlResolver – Methods accepting SiteDefinition as a parameter were obsoleted in favor of new overloads accepting Application.
- EPiServer.Web.SimpleAddressResolveContext – The SiteId property is obsolete in favor of the ApplicationName property.
Routing context changes
- EPiServer.Core.Routing.Pipeline.UrlResolverContext – The HostDefinition property is obsolete in favor of the ApplicationHost property.
- EPiServer.Core.Routing.Pipeline.UrlGeneratorContext – The Host property is obsolete in favor of ApplicationHost. The CurrentHost property is obsolete in favor of CurrentApplicationHost.
- EPiServer.Web.Routing.ContentRouteData – New constructor parameter Application. Constructor parameter HostDefinition was replaced with ApplicationHost.
- EPiServer.Web.Routing.RoutingOptions – Property UsePrimaryHostForOutgoingUrls was obsoleted. The system now always prefers primary hosts for URL generation (except in edit or preview mode with relative URLs). Property UseEditHostForOutgoingMediaUrls was obsoleted. Configure application host with type Media instead.
UI URL segment change
The default UI URL segment has changed from /EPiServer to /Optimizely.
Module-specific URL segments have also been updated to remove EPiServer branding. The following module paths have changed:
CMS 12 module path | CMS 13 module path |
|---|---|
/EPiServer/EPiServer.Cms.UI.Admin/ | /Optimizely/Settings/ |
/EPiServer/EPiServer.Cms.UI.Settings/ | /Optimizely/Profile/ |
/EPiServer/EPiServer.Cms.UI.VisitorGroups/ | /Optimizely/VisitorGroups/ |
/EPiServer/EPiServer.Cms.UI.ContentManager/ | /Optimizely/ContentManager/ |
/EPiServer/EPiServer.Cms.Forms.UI/ | /Optimizely/Forms/ |
/EPiServer/EPiServer.Cms.UI.Webhooks/ | /Optimizely/Webhooks/ |
/EPiServer/EPiServer.Cms.UI.Credentials/ | /Optimizely/Credentials/ |
/EPiServer/Optimizely.Graph.Cms/ | /Optimizely/GraphQL/ |
/EPiServer/Optimizely.Cms.OpalChat/ | /Optimizely/OpalChat/ |
/EPiServer/EPiServer.Cms.TinyMce/ | /Optimizely/TinyMce/ |
/EPiServer/EPiServer.Cms.UI.Extensibility/ | /Optimizely/Extensibility/ |
/EPiServer/EPiServer.Cms.DamIntegration.UI/ | /Optimizely/DamIntegration/ |
Update any bookmarks, integrations, scripts, or hard-coded references that rely on the previous /EPiServer/ URL format.
UriSupport replacement
The EPiServer.UriSupport class is obsolete. Resolve a singleton instance of IUriSupport from the DI container as a replacement. Members have been moved to dedicated classes:
Removed members | Replacement |
|---|---|
HttpLocalhostUri, SiteDefinitionResolver, RemoveQueryStringDelimeter, Clear | Removed (no longer used) |
SiteUrl | EPiServer.Web.SiteDefinition.SiteUrl |
UIUrl, UtilUrl, ResolveUrlFromUIBySettings, ResolveUrlFromUIAsRelativeOrAbsolute, AbsoluteUrlFromUIBySettings, ResolveUrlFromUtilBySettings, AbsoluteUrlFromUtilBySettings | EPiServer.Web.UIPathResolver |
InternalUIUrl, InternalUtilUrl | EPiServer.Web.UIOption |
IsStringWellFormedUri, IsSchemeSpecified, Combine, BuildQueryString, AddQueryString, AddLanguageSelection, Split, SplitNoDelim, IsDataUri | EPiServer.Web.UriUtil |
AddValuesToCollection | System.Collections.Specialized.NameValueCollection |
EscapeUriSegments | EPiServer.UrlEncode |
EPiServer.Web routing changes
- EPiServer.Web.HttpRequestSupport – Method IsSystemDirectory was removed in favor of EPiServer.Web.UIPathResolver.IsSystemPath.
- EPiServer.Web.PermanentLinkUtility – Method TryParseGuid was removed in favor of System.Guid.TryParse.
- EPiServer.Web.PropertyControls.FileSortOrder – Values DateLastAccessed and DateLastAccessedDesc were removed because they are no longer used.
- EPiServer.Web.Routing.AncestorReferencesLoader – Parameter contentEvents was removed in the constructor.
- EPiServer.Web.Routing.RoutingConstants – Constant NodeKey was removed because it is no longer used.
- EPiServer.Web.Routing.RoutingOptions – Method ConfigureForExternalTemplates was removed in favor of EPiServer.Web.Templating.TemplateOptions.ConfigureForExternalTemplates.
- EPiServer.Web.UIPathResolver – The parameterless constructor was removed. The static Instance method was obsoleted. Inject or retrieve the UIPathResolver singleton instance from the service container.
IContentRouteEvents removal
- EPiServer.Web.Routing.IContentRouteEvents – Interface removed. Use IContentUrlResolverEvents or IContentUrlGeneratorEvents instead. The individual events map as follows:
- CreatingVirtualPath → IContentUrlGeneratorEvents.GeneratingUrl
- CreatedVirtualPath → IContentUrlGeneratorEvents.GeneratedUrl
- RoutingContent → IContentUrlResolverEvents.ResolvingUrl
- RoutedContent → IContentUrlResolverEvents.ResolvedUrl
EPiServer.Cms.AspNetCore routing
- EPiServer.Core.Routing.Pipeline.UrlResolverContext – Property RemainingPath was removed in favor of property RemainingSegments.
- EPiServer.Core.Routing.Pipeline.UrlResolverContextExtensions – Extension method GetNextRemainingSegment was removed in favor of method GetNextSegment.
- EPiServer.Cms.AspNetCore.Routing.ControllerActionEndpointSelectorPolicy – Behavioral breaking change: when no action name constraint exists in the route, the "Index" method is selected first (if available) instead of the first valid endpoint by method sorting.
- System.Web.IHttpHandler – This feature was removed.
CMS routing behavioral changes
- When a page has two language versions, and one language version is configured to use the other as a fallback, if the primary language version expires, CMS 13 displays the fallback language instead of showing a 404.
- EPiServer.Web.Routing.ContentRouter – The Instance field was changed to a property.
- EPiServer.Web.Routing.RoutedContentEvaluationResult – The NotFound and OK fields were changed to properties.
- EPiServer.Globalization.IUpdateCurrentLanguage – Methods UpdateLanguage and UpdateReplacementLanguage were removed in favor of method SetRoutedContent.
- RouteArguments.MatchWildcardHost – Obsolete. Use MatchHost instead.