Upgrade to CMS 7.5

Previously it was possible to pass in a ID query parameter to control which page that was routed to. This is typically needed to be able to route “classic” links, for example http://sitehost/templates/Page.aspx?id=12. If routing to classic links (like the one in the example) is needed, a special route to handle them needs to be registered. This route can be registered as below:

The default support for searching for files in the SearchDataSource has been removed. The SearchService in the Alloy MVC template package can be used as a reference implementation to see how file search can be implemented.

If you rendered your images by setting the src attribute to the @Url.ContentUrl(Model.CurrentPage.PageImage) and added the edit attributes to the image tag to make editable in the edit user interface, then you need to change your code to either use PropertyFor or set the EditAttributes on a wrapping element.

<img src="@Url.ContentUrl(Model.CurrentPage.PageImage)" @Html.EditAttributes(x =/> x.CurrentPage.PageImage)/>

should be changed to

<div @Html.EditAttributes(x => x.CurrentPage.PageImage)> <img src="@Url.ContentUrl(Model.CurrentPage.PageImage)"/> </div>

or

@Html.PropertyFor(Model.CurrentPage.PageImage)

When content has a stop publish date the behavior of the edit UI has changed. Previously, a warning in the notification field would always be visible if stop publish had been set. This has been changed so that the warning is hidden until the stop publish date is in the near future. How long before the stop publish date the warning becomes visible is controlled by the expirationNotificationPeriod setting in the applicationSettings element in the episerver section of the site configuration files. The default is 60 days.

If the ContentProvider does not support EPiServer.Core.ContentProviderCapabilities.Wastebasket and gets a call on MoveToWastebasket a capability exception will be thrown. The EPiServer.Configuration.ContentProviderElement.FullSupportString now includes Wastebasket.

Previously sites where defined in web.config in the sites element under the episerver section as follows:

Where siteSettings contained site specific settings like for example start page id and SiteUrl. Now sites are defined in database through EPiServer.Web.SiteDefinitionRepository. Settings that are common for all sites have been moved to a new element applicationSettings under episerver element as follows:

The class EPiServer.Configuration.Settings that previously contained the settings for element siteSettings now contains the settings for element applicationSettings. Site-specific values like startPageId and SiteUrl have been obsoleted on the class Settings.

Sites can be defined in admin mode under Manage websites. To work programmatically with sites you can either use EPiServer.Web.SiteDefinitionRepository or you can use static property EPiServer.Web.SiteDefinition.Current. The property will resolve which SiteDefinition to use by checking the host on the current HttpRequest and compare which site that matches the host. In case no site matches the host or in case the code is not executing under an HTTP request the SiteDefinition that has a wildcard host '*' will be returned. If no wildcard site is defined the default SiteDefinition will be returned which has common values (for example root page) but site-specific values like SiteUrl and StartPage is not set.

The class EPiServer.Core.ContentFolder no longer implements interface EPiServer.Core.ILocalizable meaning folders no longer supports multi language and hence a folder will appear with same name in Block and Media gadgets regardless which language is selected in edit UI. During upgrade all other language versions than master language of folders will be deleted.

Two overloaded methods TryGet<T> have been added to interface EPiServer.IContentLoader to avoid usage of try/catch(ContentNotFoundException) pattern.

Due to the above introducing of TryGet<T> the recommendation is that a ContentProvider should not throw ContentNotFound exception from LoadContent implementation but instead return null if a content item does not exist.

If you had translated pages and blocks on the site, the translation for those should now be placed under the node <contenttypes>. Example:

This will affect existing translations for pages and blocks when upgrading from CMS 7 and pages when upgrading from CMS 5 or 6. Translations that should affect all content types should be placed under the node icontentdata instead of the name of a specific content type. Any existing writable files under either "lang" or "resources/languagefiles" will be updated automatically.

Weekday is a flags enum with corresponding values of the old integer that was returned. This has the following major implications:

The property Value will return an object of the type Weekday instead of an integer. You can cast the Weekday to an integer if your code expects that.

When registering a property weekday on your content type you should declare it using the type Weekday. So instead of:

1

[UIHint(``"WeekDay"``)]

2

public virtual int CakeDay { get``; set``; }

You should use:

1

public virtual Weekday CakeDay { get``; set``; }

Values was downconverted/upconverted when saved in the database. Decimal was converted to a Double and Int64 was converted to Int32. Since this might lead to data loss the support for Decimal and Int64 was removed from typed models. If you need to get back your values you should be able to change the type of your property to Double if you were using Decimal and Int32 if you were using Int64, since that's what it is stored as.

The method Move in IContentRepository returns ContentReference instead of void, for example when moving content between different content providers you will get the correct new identity as a return value.

1

ContentReference Move(ContentReference contentLink, ContentReference destination, AccessLevel requiredSourceAccess, AccessLevel requiredDestinationAccess);

The routing has been changed so it is more strict for language handling. As an example say that there is a page under root named “News” in English and “Nyheter” in Swedish. Previously the following URLs where handled as follows (given that no language mapping is defined for site hosts in config):

With the strict language routing the above URLs will be handled as follows:

Another change is that when a language to host mapping is defined then a URL like http://localhost/en/News/ will give a 404 since when there is a host mapping that defines a language then the language should not be present in URL.

Simple address routing has also been changed so language segment must not be present. Also a simple address to a language that is different than a language-host mapping will give a 404. There is a configuration setting strictLanguageRouting on configuration element applicationSettings that can be set to false to get the old more tolerant behavior.

To be able to support that any EPiServer.Core.IContent implementation can be registered using ContentTypeAttribute some changes in the API has taken place. The types BlockTypeModelScanner and PageTypeModelScanner have been removed and instead have the former base class ContentTypeModelScanner been rewritten so it handles all content types. So, in case you have written some code that hooks into typed model synchronization, you might be affected by a binary breaking change.

The attribute AvailablePageTypesAttribute has been superseded by a new attribute called AvailableContentTypesAttribute with identical functionality. You need to update any code and remove all references to the namespace EPiServer.DataAbstraction.PageTypeAvailability. Due to naming conflicts the old attribute was removed instead of obsoleted to give more accurate error messages in Visual Studio.

The DefaultMvcController and DefaultWebFormTemplate properties of EPiServer.DataAbstraction.ContentType are no longer set unless render templates are specifically set. To get the default template instead use the TemplateModelSelector.GetDefault method with the ContentType’s SupportedTemplates property. This will return the selected template, as defined in admin mode, or by its type argument and by whether it is an MVC controller or WebForms template (most specific type argument and MVC controllers take precedence).

To make it possible for XCOPY deployment to a “clean machine”, the default catalog structure for the CMS installation was changed from:

To new:

This also involves changing to relative paths in the configuration. At installation/upgrading, the legacy user interface files have been moved to the appdata folder to avoid the connection to the Program files folder. This is done in order to make deployment of entire sites to source control and arbitrary machines.

The VPP system is no longer used for storing editor generated content, which means that all CMS extensions to the VPP system are being phased out. The VPP API defined in EPiServer Framework will continue to be used for mapping in folders such as add-ons. See separate article on migrating to the new system.

The PageObjectManager class have been marked obsolete as of this version but is fully backwards compatible. It will be removed in the next version, we recommend using other technologies such as blocks or custom DDS stores depending on your requirements.

The sample templates in CMS 5 had a template that was using a Web Parts Framework built into CMS (that extended ASP.NET Web Parts). This Framework have been kept for backwards compatibility but has now been removed from the product, existing solutions built on the CMS 5 Framework for Web Parts have to be rebuilt to be able to upgrade to this version.

The sample templates in CMS 5/6 had a template that was using a component EPiServer.Blog and EPiServer.XmlRpc which no longer ships with the product, on upgrade these components and its config will be removed. If you are using this template you can request a compatibility package from EPiServer Support.

The WebDav module made it possible to work with VirtualPathProvider (VPP) based files through a WebDav client. Since VPP based files are phased out in favor of new content-based files the EPiServer.WebDav component no longer ships with the product and will be removed during upgrade.

The Subscription feature used in the CMS 4/5/6 templates, which automatically sends mail on publish, have been marked obsolete in this version. Existing solutions will continue to work but we do not recommend building new solutions on this API, it will be phased out.

Event configuration key in the load balanced or enterprise environment was changed to use HostingEnvironment.SiteName instead of siteId. If you have used enterprise configuration for events then you need to change it to the name of site from IIS.

Change <service name="{siteID}/EpiServer.Event.remote.EventReplication" /> to <service name="{siteName}/EpiServer.Event.remote.EventReplication" />.

If you have configured events with a private web config file then you need to change it from {siteId}\_Web.config to {siteName}\_web.config.

The mirroring sites configuration in the mirroring service web config has been removed. If you have used this configuration you need to change it by defining sourceConnectionStringName and destinationConnectionStringName on the provider. If a mirroring service acts both source and destination you can also define the these attributes to achieve the same functionality as before.

The siteDataSettings which is collection of siteDataSettingsElement on the EPiServer data store configuration element has been removed. You can use the dataSettings element instead. These settings are not defined by default in configuration.

The workflow extensions in CMS is based on Windows Workflow Foundation 3.5 which Microsoft has obsoleted as of Microsoft .NET 4.5. We do not recommend building new Workflow solutions on this framework. It will be removed in future versions of EPiServer CMS.

EPiLink TinyMCE plugin has been moved from Cms.UI to Cms.Shell.UI/UI/Editor/TinyMCE/Plugins/EPiLinks.cs.

In some cases a page will contain a block typed property. You can set up this block type to have a target property which will be the target for drag and drop operations in on-page edit mode. When the block overlay receives a drag and drop operation it can direct the new value to the target property.

The configuration needed to set the target property of a drag-and-drop operation on a block property type has been simplified. Previously, you had to add an editor descriptor for the block and add configuration for the sub property that should behave as the drag and drop target when in on-page edit mode. Now you only have to add the attribute DefaultDragAndDropTarget to the property on the model class. For example:

The AccessControlList and ContentAccessControlList has been slightly reworked to provide a more consistent and predictable behavior. A number of small changes could affect code dependent on one of these specific behaviors.

In addition the following changes has been introduced:

The PageProviderBase was removed and the custom page provider should be converted to content provider by inherits from the EPiServer.Core.ContentProvider. The Pageprovider configuration has been changed to ContentProvider see the following sample configuration:

The recommendation is to take a dependency on ISynchronizedObjectInstanceCache instead of using the CacheManager class. This was done / will be done for all Optimizely code. The new interface has been written to be able to replace the underlying HttpRuntime.Cache with other implementations. However you can continue to use CacheManager as before, including the methods that take a CacheDependency argument, since the underlying default implementation still rely on HttpRuntime.Cache. However it is strongly recommended to use the method Insert(string key, object value, CacheEvictionPolicy policy) if you need to control caching behavior.

When container pages was introduced with CMS 6 R2 there was a one to one mapping between pages and templates. With the release of CMS 7 a greater flexibility of adding template was added. Another big change was the conceptual change that a template defined what it can render rather than a content type assigning its template. With CMS 7.5 the ability to define the icon used for a given content type we have moved the concept of "container pages" to be a template implementation instead. You can still have content types without public templates but to get the specific "Container page" icon, you need to add a small piece of code configuration. This is part of the Alloy templates and looks as the code below:

The base class SystemPageBase was made obsolete. Instead, you can use either WebFormsBase or ContentWebFormsBase that are located in the EPiServer.Shell.WebForms namespace in the EPiServer.UI assembly. As a side note, none of the namespaces in the EPiServer.UI assembly, except the newly added classes in the EPiServer.Shell namespace, are intended for public usage. They will, however, remain as long as there are need for them in the built in user interface (mostly the administrative interface).