Migrating from CMS 4.62 to CMS 5 SP1

Introduction 

Support is only currently available for upgrade of EPiServer CMS 5 R1 sites to EPiServer CMS 5 SP1. For further information about migrating from EPiServer CMS 4.62 to EPiServer CMS 5 R1 see the relevant technical note.

Table of Contents

• Overview of Migration Process
• Preparation
  » Set up a Copy of the Web site You Wish to Migrate
  » Set up a Destination Site
  » A note on EPsUpLoadDir and pageFolderVirtualPathProvider
• Migrating Content and Files
  » Using Export/Import
  » Using WebDAV for Migrating Files
  » Migrating Content Using the DataFactory Webservice
• Remote Web site Settings
• Mirroring Settings
  » EPiServer Page Mirroring
  » HTML and XML Mirroring
• Scheduled Jobs
• Convert Project to ASP.NET 3.0 / Microsoft Visual Studio 2005
  » Conversion Wizard
  » Add New Assembly References
• Code Conversion
  » Convert Content Framework Templates to MasterPages
  » DataSources
  » Configuration
  » PageData Cache
  » Security
  » User Authentication and Personalization
  » Custom Property Types

Overview of Migration Process

Preparation

Set up a Copy of the Web Site You Wish to Migrate

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. 

• Upgrade the copy to EPiServer CMS 4.62

EPiServer CMS 4.62 is the only supported version for migrating to EPiServer CMS 5 R1. Use EPiServer Manager for this. 

• Change LongString properties to XhtmlString

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. 

• Convert Form-properties to XForm

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. 

Set up a Destination Site

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. 

• Install EPiServer CMS 5 R1

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. 

• Map upload folders to VPPs

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.

A Note on EPsUploadDir and pageFolderVirtualPathProvider

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:

1. If you have already separated the page folders from the global files you should set EPsUploadDir to a non-existing directory. This will give you simple one-to-one folder-to-VPP mappings.
2. If you have a single upload directory where both global files and page folders are stored you should let the value of EPsUploadDir point to the correct upload folder and separate the page folders from the global files after import. Note that the Permanent Link functionality is crucial for easily separating the page folders from the global files, so make sure that you are using XhtmlString rather than LongString.

Migrating Content and Files

Using Export/Import

• Export content from the EPiServer CMS 4.62 site

Open the “Export Data” tool in admin mode and select the following:



Export pages	Select the startpage as root of the export * Export files that the pages link to Export globalized pages Automatically export dependent page types
Export frames	All
Export dynamic property definitions	All
Export tabs	All
Export categories	All



• Click “Export” and save the export file locally.
  
• Import content to the EPiServer CMS 5 R1 site
  Open the “Import Data” tool in admin mode. Select the export file you created in the last step and select the root page as destination. Click “Begin Import” and wait for the process to finish.
  
• Separating the page folders from the global files
  Make sure that the VPP specified in pageFolderVirtualPathProvider has showInFileManager set to true. Open the FileManager in admin mode and move everything except the page folders to the folder you will be using as global upload.
  
• Use WebDAV to move additional files
  The “Export files that the pages link to” option will, as the name suggests, include any files that are directly linked to by a page. If you have files that are not referenced directly, for instance files only shown in a file tree, you will have to move them using WebDAV.

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

Using WebDAV for Migrating Files

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:

• Cannot be used for migrating files in page folders

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. 

• Cannot be used for migrating files stored in VersioningFileSystem UFS folders

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.

Migrating Content Using the Datafactory Webservice

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, EPiServer.DataFactory.

Remote Web Sites Settings

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:

1. The ‘Shared secret for signature’ has been replaced in EPiServer CMS 5 with a new entry in ‘Permission for Functions’ called ‘Allow the user to act as a web service user’. Instead of entering a shared secret on the local site you need to give the user the ‘Allow the user to act as a web service user’ permission on the remote site. The user referred to here is the one entered when creating the remote site entry on the local site.
2. Because of the above, only the source site requires a definition of the remote site. In 4.62 both sites required a remote site entry to point at each other in order to resolve the signature.
3. Remote Web Sites in EPiServer CMS 5 are not backwards compatible with EPiServer CMS 4.62. You cannot create a remote site entry on an EPiServer CMS 5 site to point to an EPiServer CMS 4.62 site and vice versa. There are currently no plans to support this scenario.

The technote Mirroring - Configuration and Operation contains more information about setting up remote sites in EPiServer CMS 5.

Mirroring Settings

Mirroring Channels and Destinations cannot be transferred from EPiServer CMS 4.62 and therefore must be re-created on the EPiServer CMS 5 site.

EPiServer Page Mirroring

The following differences between EPiServer CMS 4.62 and EPiServer CMS 5 should be noted with regards to EPiServer Page Mirroring:

1. Page Mirroring in EPiServer CMS 5 is not backwards compatible with EPiServer CMS 4.62 due to extensive improvements in the functionality. You cannot mirror pages from an EPiServer CMS 5 site to an EPiServer CMS 4.62 and vice versa. There are no plans to support this scenario in the future.
2. The changes made to inter-page link handling in EPiServer CMS 5 allow for more flexible page mirroring. For example, it is possible to mirror pages that contain links to other pages on the site without permanently breaking those links if the linked pages are not mirrored at the same time. The links will be broken (unless mirrored back to the same site) while the linked pages are not mirrored. However, if any of the linked pages are subsequently mirrored at a later time then the link on the first page will automatically start to work again.

HTML and XML Mirroring

The following differences between EPiServer CMS 4.62 and EPiServer CMS 5 should be noted with regards to HTML and XML Mirroring:

1. HTML and XML Mirroring in EPiServer CMS 5 is not backwards compatible with EPiServer CMS 4.62 due to extensive improvements in the functionality. You cannot point an HTML or XML Mirroring Destination at a location on disk where EPiServer CMS 4.62 has written HTML or XML Mirroring output.
2. Multi-language sites are now supported. EPiServer CMS 5 will create a sub-folder under the chosen destination root folder for each language that is mirrored.

Scheduled Jobs

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.

Convert Project to ASP.NET 3.0 / Microsoft Visual Studio 2005

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.

Conversion Wizard

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.  

Add new assembly references

The following assemblies are new or have changed name in EPiServer CMS 5:

• EPiServer.Legacy4 – This namespace contains classes that are obsolete in EPiServer CMS 5, use this assembly until the code has been completely rewritten to use the EPiServer CMS 5 API ().
• EPiServer.Web.WebControls – In order to conform to ASP.NET standards all controls previously located in the EPiServer.WebControls namespace have been moved to a separate assembly and have been given a new namespace. Note that the Legacy4 assembly still uses the EPiServer.WebControls namespace.
• EPiServer.Configuration – This namespace contains the new configuration classes based on the ASP.NET 2.0 standard.
• EPiServer.Wsrp – the ElektroPost.Wsrp assembly and namespace have been renamed. 

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. 

Code Conversion

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.

Convert ContentFramework Templates to MasterPages

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.  

DataSources

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: 

Configuration

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.

Note: All values in the AppSettings collection are returned as strings so you will have to convert them to the correct type manually:

PageData Cache

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  

Security

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:

User Authentication and Personalization

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

Custom Property Types

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.