For information about breaking changes for the EPiServer 7 **platform**, please refer to to the [EPiServer Framework SDK documentation](🔗).
## CMS Specific Breaking Changes
The following has been renamed, moved or changed behavior:
UnifiedFile.UnifiedFileUndoedCheckOut was renamed to **UnifiedFileCheckOutUndone**.
IStringFragment moved from EPiServer.SpecializedProperties to **EPiServer.Core.Html.StringParsing**.
Default constructor for PageData does not add property PageCategory anymore. Typically constructors should not be used, use the **IPageDataFactory** instead.
PermanentLinkMapper is no longer just a facade over PermanentLinkMapStore and its \[Serializable\] attribute has been removed. This affects serializable classes that have IPermanentLinkMapper fields.
PageData.Category will no longer throw an exception if no property called “PageCategory” exist, only return null.
Before DataFactory raises its Created/Saved/Published/CheckedIn event, it now updates the eventArgs.Page property with the committed value.
Usage of the System.ApplicationException has been removed, Microsoft does not recommend using it for custom exceptions.
PageVersionDB renamed to ContentVersionDB.
PageDB, PageLoadDB and PageSaveDB has been renamed to ContentDB, ContentLoadDB and ContentSaveDB. They also now work with ContentReference and IContent compared to PageReference and PageData.
DeleteVersion has been moved from PageSaveDB to ContentVersionDB.
The PageReferenceCollection inherits from ContentReferenceCollection which cause semantic breaking change. You can not longer directly cast PageReferenceCollection to IList you need to do as following pagerefs.Where(cr => cr is PageReference).Cast().ToList().
PageType no longer accepts values of filename that are not proper virtual paths.
Some methods on PageData such as GetPageDirectory, GetPageLanguage, QueryAccess and QueryDistinctAccess has been moved to extension methods. If you get compile warnings on these methods make sure you have a using statement on EPiServer.Core.
The meta data property PageDelayedPublish has been removed. It was only used as an indicator when saving a page, saying that it should be set to the state delayed publish. Instead a new SaveAction called DelayedPublish has been added. Use that when saving a page if you want it to be delayed published. If you want check if a page is delayed publish you should check its Status property.
### General API
To support handling of other content than pages (typically global blocks) some methods/properties that previously worked with PageReference has been changed to work with **ContentReference** instead.
**Affected users:** Developers that work with DataFactory.
**Description:** To support storing of other content than pages (typically global blocks) DataFactory has been refactored a bit, below are a list of some of the changes:
Property ProviderMap now returns a **ContentLinkMap** instead of a PageLinkMap. ContentLinkMap has a similar signature to PageLinkMap but handles **ContentProviders** instead of PageProviders.
### PropertyData.Value for some property types
**Affected users:** Developers who cast values of **PropertyXhmlString**, **PropertyXForm**, **PropertyUrl**, **PropertyDocumentUrl** and **PropertyImageUrl** to strings.
**Description:** To support defining properties on typed models in a simple and unambiguous way, as well as aligning the data returned by the affected property types with the PropertyDataType they define, the type of the returned value from these types have changed. This also affects the type of the value returned by the default indexer of PageData (CurrentPage\["MainBody"\] for example). The property types now return values of these types:
EPiServer 7 offers a compatibility mode which reverts the change. That is, the properties continue to return strings like in EPiServer 6 when the site runs in compatibility mode. To use the compatibility mode, include the **LegacyPropertyValueType** option in the **operationCompatibility** attribute of your **siteSettings** element in **episerver.config**.
**This compatibility mode should be considered experimental** and a way to get a site up running under EPiServer 7 quickly. **LegacyPropertyValueType should not be used in production environments**. Before an upgraded site is deployed to production it should be checked so that it does not assume that the mentioned types return strings.
Also, it is not possible to run sites in compatibility mode and use properties of the affected types in strongly typed models. That would cause ambiguities so the CMS throws an exception if you try to do this.
**To refactor the code** so it does not assume that the mentioned types return strings, you can start by using the following regular expressions in Visual Studio to find common usages:
**\\\[:q\\\]:b+as:b+string** (matches constructs like 'CurrentPage\["MyProp"\] as string')
**\\(string\\):b\*:w+\\\[:q\\\]** (matches constructs like '(string)CurrentPage\["MyProp"\]')
These regexes will of course match many things that are not property access.
Many instances of actual property access are not problematic, only access to the affected types may require refactoring.
You may have other property access that is not found by these regexes, but nontheless requires refactoring.
You can use the **GetPropertyValue extension method** (with several overloads) in the **EPiServer.Core** namespace to simplify some of the refactoring. Add EPiServer.Core in a using statement in your codebehind file (or Import directive in codefront) and then change for example **(string)CurrentPage\["MainBody"\]** into **CurrentPage.GetPropertyValue("MainBody")** to retain the same behavior.
### Changed default editor for PropertyLongString
In the supported database versions there is no longer any reason to use different database columns depending on string length. Because of this, the default backing type for the CLR string type in strongly typed models is LongString and not String. With this change, the default edit control for LongString has been changed to a TextBox (like for String).
To use a TextArea instead of a TextBox for a string property on a typed model, apply a UIHint attribute to the property:
To limit the length of a string (but retain LongString as backing type), apply the StringLength attribute:
If you want to keep the LongString editor from EPiServer CMS 6, include the **LongStringLegacyControl** option in the **operationCompatibility** attribute of your **siteSettings** element in **episerver.config**.
Previously validation of PageData instances was only performed when you saved pages through the UI, when saving through API no validation was performed. This has been changed so when calling **DataFactory.Save** a validation of the passed in content will be performed. It is however possible to prevent validation by using flag SaveAction.SkipValidation.
### PermanentLinkMapStore, PermanentPageLinkMap, IPermanentLinkMapper
In namespace **EPiServer.Web,** the class PermanentPageLinkMap has been made obsolete and replaced by class **PermanentContentLinkMap**. Methods in PermanentLinkMapStore and IPermanentLinkMapper has been changed according to this.
### Localization Management
**Affected users:** If you directly call the class EPiServer.Core.LanguageManager.
EPiServer.Core.LanguageManager is obsolete, since it has been replaced by a new localization system in the **EPiServer.Framework.Localization** namespace called **LocalizationService** with comparable functionality. The most commonly used methods in LanguageManager will continue to work even though we recommend to make the transition to the new API as soon as possible.
The class **PageCoreData** has been made obsolete and is replaced by class **ContentCoreData**. To load a ContentCoreData you should use EPiServer.DataAbstraction.IContentCoreDataLoader instead of using static Load methods which was the case with PageCoreData. This API is primarily used internally by EPiServer.
The VPP configuration and registration has been moved to Framework.
The /configuration/episerver/virtualPath configuration element has been modified and moved to framework.
The provider list is now in /configuration/episerver.framework/virtualPathProviders and the additional configuration attributes are now passed as provider settings in specific provider elements in the list.
The /configuration/episerver/virtualPathMappings element has been moved to /configuration/episerver.framework/virtualPathMappings.
The related properties and classes in EPiServer.Configuration in CMS (VirtualPathElement class, EPiServerSection.VirtualPathSettings, EPiServerSection.VirtualPathMappings) are now obsolete.
(The classes MappedVirtualFile, VirtualFileEx, VirtualPathMappedProvider, VirtualPathNonUnifiedProvider VirtualPathRegistrationHandler, MimeMapping and StaticFileHandler have been moved to the EPiServer.Framework assembly. These, however, remain in the EPiServer.Web and EPiServer.Web.Hosting namespaces and type forwarding is in place for these types, so they should not cause breakage.)
The EPiServer.Web.Hosting.VirtualPathHandler.InitializeProviders method signature has changed as well as the functionality. It now only does CMS specific initialization and expects a dictionary populated with already instantiated and registered providers from VirtualPathRegistrationHandler in framework.
### VPP Filtering
**Affected users**: This has been an undocumented feature that is not used by default in EPiServer CMS.
**Description**: The feature of VPP Filtering is removed, the <filters/> element is removed from configuration. The following APIs has been removed in namespace EPiServer.Web.Hosting:
VirtualPathVersioningProvider.AddFilter (applies to all providers)
VirtualPathVersioningProvider.Filters (applies to all providers)
### IReadOnly + IReadOnly<T>
**Affected users**: You will only be affected by this change if you implement any of these interfaces or directly reference it instead of using the class PageData.
**Description**: Interfaces have moved from namespace EPiServer.Core to EPiServer.Data.Entity in EPiServer.Data.dll. IReadOnly also has a new method **CreateWritableClone** that requires an explicit interface implementation if you implement this interface yourself (previously only IReadOnly<T> had this method). The reason for this change is to share the interface with other products.
### Translate Methods in PageBase and UserControlBase
**Affected users**: You will only be affected by this change if you have accessed the Translate(String) or TranslateForScript(String) in PageBase or UserControlBase without having imported the EPiServer namespace or if you have overridden any of the above methods in UserControlBase.
**Description**: The Translate methods in UserControlBase and PageBase has been made protected as they were inconsistent and only provides conveniance access to the new EPiServer.Framework.Resources.ResourceLocator. Public access is still made possible through legacy extension methods marked as obsolete.
### Maximum Size of PropertyString
**Affected users**: If you have custom properties that override MaxSize on PropertyString and gives it a value of more than 450 characters.
**Description**: The default maximum value of PropertyString is 255 characters but it was theoretically possible to override that value and set it up to 1,999 characters even though not documented. The database schema has now been changed and supports only up to 450 characters which aligns the model for shorter indexable strings with Dynamic Data Store. For large strings it is recommended to use the data type PropertyLongString.
### Creating PropertyData Objects
**Affected users:** If you have custom properties that has a constructor that takes an IPermanentLinkMapper or if you are relying on fallbacks between Assemblies after registrating property types.
**Description:** When a PropertyData is created we will no longer look for a constructor that takes a IPermanentLinkMapper. Instead we will run the BuildUp method of the current IServiceLocator to inject dependencies. We have also removed the fallback that looked for missing property types in all loaded assemblies regardless if the assembly definition matched or not.
### New Line Character in XML Translation Files
**Affected users**: You could get a problem if you have used the constant Environment.NewLine when working with translated strings in CMS.
**Description**: There has been a change in the way a new line in the XML translations files is represented in code. In EPiServer CMS 6 (R2) the new line would be "\\r\\n", while in the new line will only be represented with "\\n" in Falcon. The reason for this change in to fulfil the XML specification, see [\<\<http://www.w3.org/TR/2008/REC-xml-20081126/#sec-line-ends>>](🔗).
### CMS and Shell: Static Typed Resource Classes Have Been Removed
**Affected users**: Any access to any of these classes must change to use the new **LocalizationService** API:
**Description**: Any gadget attributes that previously used any of these as **ResourceType** will now have to change their **TextResourceKey** to a full resource key.
From: \[GadgetAction(TextResourceKey = "Edit", ResourceType = typeof(EPiServer.Shell.Resources.Texts))\]
To: \[GadgetAction(TextResourceKey = "/EPiServer/Shell/Resources/Texts/Edit")\]
The HtmlHelper Translate extension method have been moved from namespace EPiServer.Cms.Shell in assembly EPiServer.Cms.Shell.UI to namespace **EPiServer.Shell.Web.Mvc.Html** in assembly EPiServer.Shell.
### Module Routing Configuration with Many Routes
**Affected users**: You will only be affected by this change if you access the **ShellModule** object or are creating a **module.config** file with routes.
**Description**: The configuration has been changed to have a collection of route elements underneath a single routes element. The **Route** property on the **ShellModuleManifest** has not been made obselete because this interferes with serialisation, however it has been changed to be a quick entry point for the first item in Routes. The RouteDescription has a new property**ClientSideOnly** which determines whether the route should be loaded into the server side routing model.
### PageDefinition CheckUsage
**Affected users**: You will be affected by this change if you are using the **CheckUsage** method of the PageDefinition class.
**Description**: The CheckUsage method has been moved to **IPropertyDefinitionRepository** and refactored so there is a CheckUsage that returns a boolean and a GetUsage that returns **ContentUsage**.
### DataAccess Layer
**Affected users**: You will be affected by this change if you are using any of the classes in the **EPiServer.DataAccess** namespace directly.
**Description**: Several of the classes in the DataAccess namespace have gone through a major refactoring to improve testability. These classes were all marked with the phrase “_This member supports the EPiServer infrastructure and is not intended to be used directly from your code”._
Classes PageDB, PageLoadDB, PageListDB, PageSaveDB, PageVersionDB has been renamed to **ContentDB**, **ContentLoadDB**, **ContentListDB**, **ContentSaveDB** and **ContentVersionDB** and have been refactored so they can handle **IContentData/ContentReference** instead of PageData/PageReference.
### Relative URLs in Markup
**Affected users**: You will be affected by this change when switching from FriendlyUrlRewriteProvider / UrlRewriteModule to HierarchicalUrlRewriteProvider / RoutingUrlRewriteModule.
**Description**: You can no longer use relative URLs in markup, you must explicitly call **ResolveClientUrl(\[relativeUrl\])**. Note that this does not affect relative URLs passed as attribute values to ASP.NET web controls – ASP.NET web controls will implicitly call ResolveClientUrl.
### Log Service / Statistics
**Affected users**: Any access to any of the following classes, methods and properties are no longer valid:
public static System.Void EPiServer.Web.Hosting.VirtualPathUnifiedProvider.LogFileRequest (System.String p1);
**Description**: Log Service / Statistics has been removed as a feature, therefore all classes, methods and properties related to that functionality have been removed as well from the API.
### Import/Export API
**Affected users:** You might be affected by this change if you have any code (like for example event handlers) targeting the import export APIs. The namespaces that has most changes are **EPiServer.Enterprise** (including sub namespaces) and **EPiServer.Core.Transfer**.
**Description:** The changes where introduced in order to support copy/import/export and mirroring for other content types (for example, global blocks) than just Pages.
### DataFactory Compatibility with CMS 5 R1
**Affected users:** If you used the **operationCompatibility** flag in web.config to simulate the old behavior of the Save and Delete method in DataFactory.
**Description:** The operationCompatibility flag no longer supports simulating how methods Save and Delete worked for DataFactory in CMS 5 R1. In case of Delete compatibility, it fired events for child pages and in case of Save compatibility and did an in-place update of the PageData instance. No changes are required to your code or configuration but none of these compatibility measures will be enabled.
### PageDefinition Obsoleted, Replaced by PropertyDefinition
**Affected users**: Developers who have made more advanced plug-ins, that worked directly against page definitions.
**Description**: EPiServer.DataAbstraction.PageDefinition is renamed to **EPiServer.DataAbstraction.PropertyDefinition**. This is done by obsoleting PageDefinition, moving its functionallity into PropertyDefinition, and having PageDefinition inheriting from PropertyDefinition.
So PageDefinition will still exist, but should be replaced with PropertyDefinition in the code. Some support classes has been renamed as well, but in all cases the original class has be left behind, but set to obsolete. This was done to minimize the breaking change.
**Reason**: The name PageDefinition was very confusing since it had nothing to do with the definition of a page. Rather, it was the definition of a property.
### Web Control InputPageDefinitionType Renamed to InputPropertyDefinitionType
**Affected users:** Developers who have used the webcontrol EPiServer.Web.WebControls.InputPageDefinitionType in their pages.
**Description:** Since PageDefinition has been renamed **PropertyDefinition** the name of this web control was misleading. This is a straight rename so all functionality will stay the same.
### String Fragments on XHTML Property Now Supports Read-Only Mode
**Affected users:** Developers who have used properties or methods on the StringFragmentCollection that is specific to the generic List<T> class.
**Description:** The StringFragmentCollection is exposed on the PropertyXhtmlString but did not support read-only mode making the page cache mutable. Therefore the StringFragmentCollection has changed to inherit from **System.Collections.ObjectModel.Collection<T>** instead of System.Collections.Generic.List<T> and does not have a ToReadOnly method.
### SearchDataSource Have Been Rewritten to Use the EPiServer Search Index – Many Members Marked as Obsolete
**Affected users:** Developers who has inherited from SearchDataSource. Developers who have used SearchDataSource on their page type templates.
**Description:** The SearchDataSource has been rewritten to utilize the EPiServer Search product. This means that in order to get any results from SearchDataSource without specifying Criterias you now need an EPiServer Search index.
The following members on SearchDataSource have been marked as obsolete:
protected virtual IndexServerResults PerformFileSearch(TextSearchParameters searchParams)
protected virtual IndexServerResults PerformIndexServerSearch(TextSearchParameters searchParams)
protected virtual IndexServerResults PerformUnifiedFileSystemSearch()
The reason for the obsoletion of these members is that they are no longer used when populating the SearchDataSource. EPiServer Search now handles indexing of versioned files and files will therefore be included in the results from SearchDataSource.
### VersioningDirectory Search Will Only Use Certain Values on UnifiedSearchQuery
**Affected users:** Developers using the Search method on VersioningDirectory.
**Description:** The Search method has been rewritten and only uses the FreeTextQuery and Modified dates of the specified UnifiedSearchQuery. FileNamePattern, Path and MatchSummary will be ignored.
### Obsolete Properties
The following properties are obselete:
PropertyAppSettings (suggested alternative is PropertyDropDownList)
PropertyLanguageBranch (suggested alternative is PropertyLanguage)
The following new property has been added:
IDictionary\<string, Guid> PageTypesMap
**Affected users:** You will be affected by this change if you have your own implementation of the aforementioned interface.
**Description:** The new member of the interface was introduced in order to provide matching of existing strongly typed page types with imported page types.
### Global Error Handling via E-mail
**Affected users:** If you configured globalErrorMail in web.config it will not have any affect.
**Description:** CMS no longer renders the error reporting feature that could be enabled by globalErrorMail. Both settings _globalErrorMail_ and _globalMailHandler_ are ignored. We recommend using custom error pages to enable visitors to report problems on your site and use the built-in logging capabilities to send e-mail reports.
**Affected users:** Developers who has implemeted thier own dynamic content, either by implementing the interface IDynamicContent, or inheriting from the abstract class DynamicContentBase.
**Description:** The IDynamicContent interface is being phased out to be able to support blocks, pages and MVC. It will continue to work in EPiServer 7 for pages only and only on WebForms. Because of this change the base class DynamicContentBase have a changed implementation where instead of overriding GetControl and Render you have to implement either IDynamicContentControl or IDynamicContentView depending on your requirements, more information in the Dynamic Content section in the SDK.
**Description:** This enum is obsolete and superseded by EPiServer.Security.ProviderActions in EPiServer.Framework. All usages within EPiServer are changed to use the new enum, which affects the following method signatures:
EPiServer.Security.ProviderCapabilities.IsSupported(string providerName, EPiServer.Security.ProviderCapabilities.Action action)
EPiServer.Security.ProviderCapabilitySettings.ctor(EPiServer.Security.ProviderCapabilities.Action action, params string\[\] properties)
Users who use a custom role or membership provider and use EPiServer.Security.ProviderCapabilities to register the capabilities of that provider and/or use the class to query for capabilities of registered providers
Users who have certain parts of the sample code in AlloyTech’s Register.aspx and PersonalSettings.ascx
Users who have customized (overridden) certain parts of the episerver UI AdminGroup.aspx
### EPiServer CMS 5 Editor No Longer Supported
The entire EPiServer CMS 5 Editor has been removed, and is therefore no longer supported. Refer to the list of [**Class Changes**](🔗) to facilitate adaption of existing code to the new framework.
The following classes and interfaces has been removed in the CMS/EPiServerNET project:
public virtual EPiServer.Editor.EditorToolOption get\_EditorToolOptions ();
public virtual System.Void set\_EditorToolOptions (EPiServer.Editor.EditorToolOption p1);
public virtual EPiServer.Editor.EditorToolOption get\_EditorToolOptions ();
public virtual System.Void set\_EditorToolOptions (EPiServer.Editor.EditorToolOption p1);
public EPiServer.Editor.EditorToolOption get\_LongStringSettings ();
public System.Void set\_LongStringSettings (EPiServer.Editor.EditorToolOption p1);
public static EPiServer.Security.Permission EditorUnlimitedFunctions;