Breaking changes in CMS 7

For information about breaking changes for the Optimizely Content Management System (CMS 7) platform, see the EPiServer Framework SDK documentation.

The following has been renamed, moved or changed behavior:

To support handling of other content than pages (typically global blocks) some methods or properties that previously worked with PageReference was changed to work with ContentReference instead.

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:

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:

CMS 7 offers a compatibility mode that reverts the change. That is, the properties continue to return strings like in CMS 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 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:

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 code-behind file (or Import directive in code front) and then change for example (string)CurrentPage\["MainBody"\] into CurrentPage.GetPropertyValue("MainBody") to retain the same behavior.

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 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.

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.

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 you should 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 CMS.

Users – This has been an undocumented feature that is not used by default in CMS.

Description – The feature of VPP Filtering is removed, the <filters/> element is removed from configuration. The following APIs was removed in namespace EPiServer.Web.Hosting:

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.

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 convenient access to the new EPiServer.Framework.Resources.ResourceLocator. Public access is still made possible through legacy extension methods marked as obsolete.

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, use the data type PropertyLongString.

Users – If you have custom properties that have a constructor that takes an IPermanentLinkMapper or if you are relying on fallbacks between Assemblies after registering property types.

Description – When a PropertyData is created we will no longer look for a constructor that takes a IPermanentLinkMapper. Instead, you 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.

Users – You could get a problem if you have used the constant Environment.NewLine when working with translated strings in CMS.

Description – There was a change in the way a new line in the XML translations files is represented in code. In 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 fulfill the XML specification, see End-of-Line Handling.

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.

Example:

From: [GadgetAction(TextResourceKey = "Edit", ResourceType = typeof(EPiServer.Shell.Resources.Texts))]

To: [GadgetAction(TextResourceKey = "/EPiServer/Shell/Resources/Texts/Edit")]

The HtmlHelper Translate extension method were moved from namespace EPiServer.Cms.Shell in assembly EPiServer.Cms.Shell.UI to namespace EPiServer.Shell.Web.Mvc.Html in assembly EPiServer.Shell.

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 was changed to have a collection of route elements underneath a single routes element. The Route property on the ShellModuleManifest has not been made obsolete because this interferes with serialization; however, it was 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.

Users – You will be affected by this change if you are using the CheckUsage method of the PageDefinition class.

Description – The CheckUsage method was moved to IPropertyDefinitionRepository and refactored so there is a CheckUsage that returns a boolean and a GetUsage that returns ContentUsage.

Users – You are 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 or PageReference.

Users – You will be affected by this change when switching from FriendlyUrlRewriteProvider or UrlRewriteModule to HierarchicalUrlRewriteProvider or 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.

Users – Any access to any of the following classes, methods and properties are no longer valid:

Classes

Methods

Properties

Description – Log Service / Statistics was removed as a feature; therefore, all classes, methods, and properties related to that functionality were removed as well from the API.

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 have the most changes are EPiServer.Enterprise (including sub-namespaces) and EPiServer.Core.Transfer.

Description – The changes where introduced to support copy/import/export and mirroring for other content types (for example, global blocks) than just Pages.

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.

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 functionality 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 were renamed as well, but in all cases, the original class has been left behind and 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.

Users – Developers who have used the webcontrol EPiServer.Web.WebControls.InputPageDefinitionType in their pages.

Description – Since PageDefinition was renamed PropertyDefinition the name of this web control was misleading. This is a straight rename so all functionality will stay the same.

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.

Users – Developers who has inherited from SearchDataSource. Developers who have used SearchDataSource on their page type templates.

Description – The SearchDataSource was rewritten to utilize the CMS Search product. This means that to get any results from SearchDataSource without specifying Criterias you now need an Search index.

The following members on SearchDataSource were marked as obsolete:

Properties

Methods

The reason for the obsoletion of these members is that they are no longer used when populating the SearchDataSource. Search now handles indexing of versioned files and files will therefore be included in the results from SearchDataSource.

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.

The following properties are obselete:

The following new property has been added:

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 to provide matching of existing strongly typed page types with imported page types.

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. You should use custom error pages to enable visitors to report problems on your site and use the built-in logging capabilities to send e-mail reports.

Users – Developers who has implemeted their 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 support blocks, pages and MVC. It will continue to work in CMS 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 CMS are changed to use the new enum, which affects the following method signatures:

Affected users:

The entire CMS 5 Editor was removed and is therefore no longer supported. Refer to the list of Class Changes to facilitate the adaption of existing code to the new framework.

The following classes and interfaces has been removed in the CMS/EPiServerNET project: