EPiServer CMS 5 R1
Document creation date:
Document last saved:
To avoid affecting the production Web site it is recommended that a copy is used as a source for the migration process. You will have to make some changes to the page types and configuration which is not something you want to do on a live Web site. Also, exporting content will affect the performance of the exporting Web site as the process can be time consuming and will require large amounts of memory.
EPiServer CMS 4.62 is the only supported version for migrating to EPiServer CMS 5 R1. Use EPiServer Manager for this.
If you are using LongString properties on any of your page types you should change them to XhtmlString. This will enable the Permanent Link feature in EPiServer CMS 5 R1 and greatly help you avoid creating broken links when migrating. If you have any custom properties inheriting from EPiServer.Core.PropertyLongString that can contain internal links to pages or files you should rewrite them so that they inherit from EPiServer.SpecializedProperties.PropertyXhtmlString instead.
Use the “Convert Form” tool available in admin mode to convert all your forms to the XForm type. The old Form property type is no longer available in EPiServer CMS 5. Note that you also have to make sure that the pages containing the Form properties are updated to use the converted XForms or replaced with new pages using the converted XForms.
Migration from EPiServer CMS 4 to 5 is not done “in place”, instead content and files are gradually moved from the EPiServer CMS 4 site to an EPiServer CMS 5 destination.
Use EPiServer Manager to install the EPiServer CMS 5 core files, do not install any content. This Web site will serve as destination for the migration. Note that SQL Server 7 and Windows 2000 are no longer supported platforms from EPiServer CMS 5 so you might have to setup the destination site on a separate machine. After installation, modify the web.config file and set pageStart to “1” so that the root page will also be used as the start page.
Match every file folder on the EPiServer CMS 4.62 site to a VirtualPathProvider on the EPiServer CMS 5 R1 site. Each UnifiedFileSystem folder should have a matching VPP with an identical virtualName. If you are not using UFS, set up a VPP where the virtualName attribute matches the name of your upload folder.
When exporting from the EPiServer CMS 4.62 site all file paths that start with the value defined in the EPsUploadDir property (commonly named “/upload/”) will have that part of the path replaced with a placeholder. When such a file is imported on the 5 R1 site it will be placed in the VPP folder defined by pageFolderVirtualPathProvider. Here are a few suggestions on how to handle this:
|Export dynamic property definitions||All|
* Due to a bug in EPiServer CMS 5 R1 (issue# 7749) it is not possible to import a set of pages that include the rootpage. This means that you have to use the Web site’s startpage as a root when you export your content. This presents no problem unless you have several branches directly below the rootpage (not including the wastebasket) – if you export each branch separately all links between the branches will be broken. The workaround for this is to create a new page directly below the root and place all branches you wish to export below this page. You can then use the new page as root for the export.
A complement to migrating the files via export/import is to move them using WebDAV. It is important to know that the use of WebDAV for migration has two major limitations:
Pages will be assigned a new page folder when they are imported to the EPiServer CMS 5 Web site, the name of the folder on the exporting side has no relevance.
The file structure used to store a VersioningFileSystem folder on disk has no resemblance to the structure shown in the FileManager. Moving the file structure on disk via WebDAV will therefore not work.
Read the technote WebDAV in EPiServer CMS 5 for more information about how to set up WebDAV.
An alternative to using export / import is to write an application that moves data from the CMS 4.62 site to the CMS 5 R1 site using the datafactory webservice. This solution requires more work but can be more flexible depending on your needs. Please refer to the SDK regarding information about the Web service. Please refer to the SDK regarding information about the Web service, EPiServer.DataFactory.
The export / import process does not take EPiServer CMS Remote Web Sites into account. These must be manually re-created on the EPiServer CMS 5 site.
The following differences between EPiServer CMS 4.62 and EPiServer CMS 5 should be noted with regards to Remote Web Sites:
The technote Mirroring - Configuration and Operation contains more information about setting up remote sites in EPiServer CMS 5.
Mirroring Channels and Destinations cannot be transferred from EPiServer CMS 4.62 and therefore must be re-created on the EPiServer CMS 5 site.
The following differences between EPiServer CMS 4.62 and EPiServer CMS 5 should be noted with regards to EPiServer Page Mirroring:
The following differences between EPiServer CMS 4.62 and EPiServer CMS 5 should be noted with regards to HTML and XML Mirroring:
Scheduled jobs implemented as plugins in EPiServer CMS 4 will automatically work in EPiServer CMS 5 if the assembly containing the scheduled job definition is placed in the bin folder. You will however lose the configuration settings and history data.
Converting your Web project to use Visual Studion 2005, ASP.NET 3.0 and the EPiServer CMS 5 API will be a major part of the migration process. Because no two projects are identical the information in this chapter is very general and tries to cover only the most important parts.
Use the Visual Studio 2005 Conversion Wizard to migrate your project to the Visual Studio 2005. Opening the project in Visual Studio 2005 will automatically bring up the conversion wizard. See this upgrading guide from Microsoft for more specific information.
The Tech News article Experiences from migrating to EPiServer 4.61 and ASP.NET 2.0 covers migration of an EPiServer CMS 4 site from ASP.NET 1.1 to 2.0. Although the article contains no information about migration from EPiServer CMS 4 to 5 it still contains relevant information about the WebApplicationProject model and converting ContentFramework templates to MasterPages.
The following assemblies are new or have changed name in EPiServer CMS 5:
Depending on the effort you are investing in the migration it can be a good idea to do a project-wide "search and replace" to update the code according to the new namespace names. Note that if you are planning to use classes in both EPiServer.Web.WebControls and EPiServer.WebControls (Legacy4) you will have to sort out the name namespace usage manually.
During the code conversion process it is recommended to set up a separate Web site using our example templates to be used for referencing purposes.
The ContentFramework class and its related classes have been marked as obsolete and moved to the Legacy4 assembly since ASP.NET 2.0 has builtin support for visual inheritance via the MasterPage classes. You should aim to convert your ContentFramework implementation to use MasterPages instead.
In short, the ContentPlaceHolder and Content controls are used in the same way as the Region control in EPiServer CMS 4. More detailed information about MasterPages can be found at MSDN.
In EPiServer CMS 5 we have removed many of our specialized presentation controls in favor of a more generic approach using the ASP.NET 2.0 DataSource and ListSource interfaces. This means that you as a developer have more freedom in deciding how to present the data provided by our classes as any DataBoundControl can be used as a consumer. The most common specialized controls like PageList and PageTree are still available for use.
Here are some examples of how you can use DataSources and generic DataBoundControls to replace some of the specialized controls:
SearchDataSource + System.Web.UI.WebControls.Repeater
FileSystemDataSource + System.Web.UI.WebControls.TreeView
The ApplicationConfiguration class has been replaced by EPiServer.Configuration.Settings. The static Settings.Instance object provides access to settings much in the same way as Global.EPConfig in EPiServer CMS 4 except that the Settings.Instance object has a dedicated, typed property for each setting. More detailed information about the configuration in EPiServer CMS 5 can be found in the technote Configuration in EPiServer CMS 5 R1.
See also the SDK documentation article "How to Read Site Settings Programmatically".
All references to Global.EPConfig[“someSetting”] should be replaced with the appropriate configuration property from EPiServer.Configuration.Settings.Instance.
Note: It is still possible to get values from the appSettings block in web.config by using the WebConfigurationManager class. This method should be used to get project related settings that you have stored in appSettings.
string mySettingValue = System.Web.WebConfigurationManager.AppSettings("mySetting");
Note: All values in the AppSettings collection are returned as strings so you will have to convert them to the correct type manually:
int myNumber = int.Parse(WebConfigurationManager.AppSettings("myNumber"));
PageData objects are now stored as read-only objects in the cache. This means that when you call GetPage to load a page, it will be retrieved from the database (only the first access to the page), marked as read-only and added to the cache.
In EPiServer CMS 4.x you could change a page after getting hold of a PageData object and the altered data would be rendered. This could be done because each access to a page in the cache would actually make a copy of the page. In EPiServer CMS 5 the cache consists of read-only objects to ensure performance, and a call to GetPage will not automatically generate a copy. If you need to change the PageData after retrieving it from the cache you need to ask for a writeable clone. See the Read-Only PageData Cache in the SDK .
Because of new caching/paging features GetChildren( PageReference pageLink ) will not return a security filtered PageData collection (allthough the controls will). If you want it to be filtered you need to do this yourself:
PageDataCollection children = GetChildren(parentReference);
Authentication of users and storage of personalized data is provided by the Membership-, Role- and ProfileProvider model in ASP.NET 2.0. The UnifiedPrincipal class has been removed and likewise the PageBase.CurrentUser property. Use the EPiServer.Personalization.EPiServerProfile class for storing personalization information.
Any code that administers users should be completely rewritten to use the new ASP.NET 2.0 provider model. The issue is covered in more detail in the article Memership and Roles in EPiServer CMS 5 R1.
If you have created a custom login page and wish to continue using it after migrating you need to rewrite it to use the new Login control in ASP.NET 2.0. More information can be found in How to: Create an ASP.NET Login Page at MSDN.com.
For more information regarding Authentication and Authorization in EPiServer CMS 5 R1, please read the technote Authentication and Authorization in EPiServer CMS 5 R1.
The new property system has had a major facelift, and the API is not backwards compatible. You will have to rewrite your custom property types. The new property system does not remove any of the existing features you use, but they have to be utilized in a different way in EPiServer CMS 5.
See the Property Types information in the SDK documentation.