Upgrading from legacy versions

To upgrade Episerver CMS, you need to upgrade from one major version to the next, step by step. This page gathers the relevant links needed to do so, if you are on the earlier versions 4, 5, or 6. From version 7, see the Upgrading Episerver CMS sections.

This link collection is put together by Arild Henrichsen; for more detailed information, see his blog posts Migrating between EPiServer 4-5-6 is as easy as 1-2-3 (part 1) and Migrating between EPiServer 4-5-6 is as easy as 1-2-3 (part 2).

In this topic

Upgrading from EPiServer CMS 4 to Episerver CMS 5

If your existing site is pre-4.62:

If your existing site is 4.62:

Please refer to the following documentation:

https://world.episerver.com/documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-R1/Migrating-to-EPiServer-CMS/

1. Download and install .NET 3.5 SP1

2. Download and install EPiServer CMS 5 R2

3. Obtain a valid CMS 5 license

4. Prepare existing 4.62 site (source):

  • Back up existing site and database.
  • Verify that database connection string is correct.
  • Verify that paths to filesystem (upload) and admin/edit UI are correct.
  • Verify that the site is browseable, login works and it has a valid license.

5. Install a new CMS 5 R2 site (target) using CMS Manager:

  • Must use new database, but a pre-existing database user account can be used.
  • Supply a valid license.
  • Do not install Public/Demo Templates.
  • Verify that NETWORK SERVICE and IUSR_<hostname> accounts have read/write access to the web site root.
  • Verify that the site is browseable.

Note: If using IIS 5 (e.g. WinXP), only one site may be running at a time. In this case, stop the old 4.62 site and start the new CMS 5 R2 site before continuing.

6. Install and run the EPiServer Migration Tool 1.1.0.38:

7. Copy the files from the 4.62 site over to the CMS 5 R2:

  • Templates folder, language files, scripts folders, any plugins or custom properties folders.
  • Filesystem (upload) will be converted and copied automatically during the migration.
  • Merge differences between the 4.62 site Web.config and the CMS 5 R2 site Web.config (applicationSettings, upload path, UI path etc).

8. Handle breaking changes:

  • Rewrite any code that no longer compiles (see Breaking Changes documentation).
  • Redeploy files and retry.

9. Test CMS 5 R2 site:

  • Verify that site is browseable and that admin/edit login works.
  • Verify that the filesystem is intact.

Additional references for EPiServer 4/5:

Challenges when moving from EPiServer 4 to CMS 5:

Rewriting code to handle breaking changes:

Rewriting from EPiServer ContentFramework to ASP.NET 2.0 MasterPages:

Replacing EPiFields with Dynamic Content:

Handling changes in the configuration files:

Implementing the ASP.NET 2.0 Membership/Role Provider system:

Changes to the filesystem:

Troubleshooting - EPiServer 4 to 5

Errors during EPiServer 4 installation/configuration:

ERROR: Cannot install files: The installation failed, and the rollback has been performed. [The name is already in use as either a service name or a service display name]
CAUSE: A newer version of the EPiServer Scheduler service is already installed on the web server. Installing EPiServer 5.x on a system where EPiServer 4.x is installed is OK, but the other way around causes problems. 
SOLUTION: Go to Administrative Tools > Services > Stop and disable the "EPiServer Scheduler service".
OPTIONAL SOLUTION: 

  • Control Panel > Add/Remove Programs > Uninstall the EPiServer CMS 5 Scheduler service.
  • Reinstall EPiServer 4.x and EPiServer 4 Shared Components.
  • Run migration, then reinstall EPiServer 5.x and EPiServer 5 Shared Components.

For more information see:
https://world.episerver.com/blogs/Magnus-Rahl/Dates/2009/1/Problems-installing-EPiServer-4x-with-newer-versions-of-EPiServer-and-NET-present/

ERROR: 
System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> System.NullReferenceException: Object reference not set to an instance of an object.

  at LicenseRegistry.LicenseCreator.CreateLicense(License license)   at LicenseRegistry.DataAbstraction.License.CreateLicenseFile()
  at ProductUpdate.InstallUnit..ctor(Int32 licenseNumber, String licensedCompany) in C:\LicenseRegistry\Production\ProductUpdate\InstallUnit.cs:line 30
  at ProductUpdate.UpdateManager.AddLicense(Product prod, InstallUnit[] units) in C:\LicenseRegistry\Production\ProductUpdate\UpdateManager.asmx.cs:line 132
  at ProductUpdate.UpdateManager.RequestInstall(Product product) in C:\LicenseRegistry\Production\ProductUpdate\UpdateManager.asmx.cs:line 122

CAUSE: When installing EPiServer 4.62B using online package, there is a known problem with the licensing system (seems the installer tries to generate/validate a license even though a license file has been supplied).
SOLUTION: Use EPiServer Manager to create an offline installation package, and install from that instead (still using EPiServer Manager).

ERROR: System.Security.Cryptography.CryptographicException: Bad Data
CAUSE: 
Web.config is encrypted, containing lines with values that could not be decrypted (was encrypted on another server - encryption is partly based on unique machine keys).
SOLUTION: Replace the values in lines containing "ENCRYPTED" with plain-text values (can be found using EPiServer Manager on the server where the web.config was originally encypted, or insert values matching the new server).

Errors during migration from 4.x:

ERROR: Failed to register ASP.NET client scripts on this site [The system cannot find the file specified]
Cause: Migration Tool is dependent on .NET 2.0 and is conflicted because .NET 3.0 or higher is installed on the system. 
Solution: Temporarily move or rename the following folders:

  • C:\WINDOWS\Microsoft.NET\Framework\v3.0
  • C:\WINDOWS\Microsoft.NET\Framework\v3.5
    then retry the Migration Tool.

ERROR: Cannot find Stored Procedure "dbo.aspnet_CheckSchemaVersion":
SOLUTION:
 Perform the following steps:

  • Locate C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_regsql.exe.
  • Use the 4.62 database as command line argument and run with default settings.
  • Restart SQL Server.
  • dbo.aspnet_CheckSchemaVersion should now be found in the database.

Moving from CMS 5 to CMS 6 R1

Please refer to the following documentation:

1. Download and install EPiServer CMS 6 R1

2. Obtain a valid CMS 6 license

3. Upgrade the existing CMS 5 site using Deployment Center:

  • Deployment Center > EPiServer CMS > Version 6.0.530.0 > Upgrade Site with SQL Server database.
  • From the list, select the CMS 5 site you want to upgrade
  • Click Upgrade to start the process
  • On completion, close Deployment Center.

4. Install new CMS 6 license

5. Test the new CMS 6 site:

  • Verify that the site is browseable and that admin/edit login works.
  • Verify that file system is intact.

Challenges when moving from CMS 5 to CMS 6:

Handling breaking changes:

Web.config being split into multiple configuration files:

XForms being converted to the new Dynamic Data Store:

Path to admin/edit view changed because of Online Center:

Additional references for EPiServer 5 / 6:

Upgrading from CMS 5 R2 to CMS 6 RC1:

Upgrading manually (without Deployment Center) from CMS 5 R2 to CMS 6 R2:


Moving from EPiServer 6 R1 to 6 R2

Please refer to the following documentation:

1. Download and install EPiServer CMS 6 R2

2. Obtain a valid CMS 6 R2 license

3. Upgrade the existing CMS 6 R1 site using Deployment Center:

  • Deployment Center > EPiServer CMS > Version 6.1.379.0 > Upgrade Site with SQL Server database.
  • From the list, select the CMS 6 R1 site you want to upgrade.
  • Click Upgrade to start the process.
  • On completion, close Deployment Center.

4. Install new CMS 6 license

5. Test the new CMS 6 site:

  • Verify that the site is browseable and that admin/edit login works.
  • Verify that file system is intact.

Troubleshooting - EPiServer 6 R1 to 6 R2

Upgrading from CMS 6 R1 to CMS 6 R2:

Upgrading Xforms fails:

Blank page references in "Fetch-data" function:

Upgrading CMS 6 R1 sites that run .NET 4:

Things to consider when upgrading from CMS 6 R1 to CMS 6 R2:

Issues when upgrading to CMS 6 R2:

IE11 incompatibility issues patch:

Last updated: Jan 24, 2019