How to upgrade to EPiServer 7.5

This article was migrated from an older iteration of our website, and it could deviate in design and functionality.


The process of upgrading websites to EPiServer 7.5 has started, and this will definitely be appreciated by editors and developers alike. This post sums up how to upgrade an existing website to EPiServer 7.5 and migrate VPP folders to the new media system.

Estimated read time : 9 minutes

Jump to

Prerequisites

If you haven't already done so you need to download and install EPiServer 7.5 (requires an EPiServer World login).

While there you should also look under the "You might also want to download" section to download the VPP migration tool.

Upgrade the web application using Deployment Manager

First off we start Deployment Center and select the upgrade option:image

The upgrade wizard is fairly straightforward, and once completed you should see some new version numbers among the assembly redirects in web.config:

New version numbers in web.config after upgrade to EPiServer 7.5

Upgrade add-ons

To avoid error messages regarding add-on assemblies in the modulesbin folder you need to run the Upgrade/disable add-ons option in Deployment Center:

Upgrade add-ons option in Deployment Center for EPiServer 7.5

Once the process is complete…

Upgrading add-on assemblies for EPiServer 7.5

…you’ll notice updated files in the Modules app data folder and the modulesbin folder in your web root:

Add-on assemblies in modulesbin folder

Upgrade NuGet packages

Next ensure you have up-to-date EPiServer NuGet packages:
Updating EPiServer NuGet packages for EPiServer 7.5

Don't forget to include the new EPiServer.CMS.UI NuGet package to avoid errors about the EPiServer.UI assembly not being found (thanks for the tip, Frederik!):

EPiServer.CMS.UI NuGet package

Update your code where needed

At this point you’ll probably notice some errors if you try to build the website. A number of types, methods and attributes have become obsolete in EPiServer 7.5. Although several of these are optional to fix, some are breaking changes.

New AvailableContentTypes attribute

You will need to replace any AvailablePageTypes attributes with AvailableContentTypes. You’ll also need to remove any use of the EPiServer.DataAbstraction.PageTypeAvailability namespace (the Availability enum now resides in the EPiServer.DataAbstraction namespace).

Obsolete attributes in EPiServer 7.5

Rebuild and reload

If you rebuild your website you should be good to go! After logging into EPiServer you should see new version numbers among your add-ons (and most importantly, be able to make use of the new features and improvements in EPiServer 7.5):

Updated add-ons for EPiServer 7.5

Migrate VPP folders to the new media system

As of version 7.5 we are no longer required to maintain VPP files on disk. Instead we can have these “files” stored in the database, and enjoy strongly typed file access in the process.

Create content type(s) for files

If you run the migration tool without creating at least one content type you’ll encounter an error saying “Cannot find any content types for files”.

First we’ll create a general content type for VPP files (this will be the default type for VPP files being migrated). The Description property ensures any “Description” meta data is automatically migrated:

Generic content type for VPP files

We want a specific content type for image files, so we’ll create another content type and add a MediaDescriptor attribute to ensure this type is used for relevant file types. We’ll also add a Copyright property to ensure any “Copyright” meta data property is migrated:

Content type for VPP image files

Next, rebuild your website and then start the VPP migration tool, browse to your web root folder and click Connect. You should now see your website’s VPP folders and the content types created:

The EPiServer 7.5 VPP migration tool

You should now be able to click the Migrate button and be done. After the migration has completed you’ll notice there are no longer any VPP folder configuration elements in EPiServerFramework.config, and you may delete the old VPP folders:

Old VPP folders on disk

You’ll also notice that you may now access the VPP folders and files through the Media gadget, and that images have been automatically converted to our ImageFile content type because of their file extension:

The new Media gadget in EPiServer 7.5

Errors during the 7.5 upgrade process

During the upgrade process I encountered some errors in Deployment Center, but fortunately they were easy to get around.

Upgrade fails if app data folders are on a UNC file share

I ran into an “Object reference not set to an instance of an object” error during my first upgrade attempt.

Error message when upgrading to EPiServer 7.5

Looking at the error details it seemed the problem had to do with the app data folders (such as the VPP folders) being on a UNC network share.

Since I intended to upgrade the VPP folders to the new media system regardless, I simply copied all VPP folders to a local folder and changed the <appData> element in EPiServerFramework.config to reflect the change:

AppData element in EPiServerFramework.config

This assumes you use the [appDataPath] placeholder in your VPP folder path settings:

VPP physical path set using appDataPath placeholder

File lock error during upgrade

After moving the VPP folders to a local drive another error message popped up saying “The process cannot access the file '…\connectionStrings.config' because it is being used by another process.” In my case the configuration files were indeed open in Visual Studio. Closing them solved the problem. Doh.

Errors after the 7.5 upgrade process

Missing HtmlHead control adapter

The HtmlHeadAdapter class, in fact the entire EPiServer.UI.WebControls.ControlAdapters namespace, has been removed. Unless you remove it from the AdapterMappings.browser file…

Removing old control adapter from AdapterMappings.browser

…you’ll get an exception saying “Could not load type EPiServer.UI.WebControls.ControlAdapters.HtmlHeadAdapter”:

HtmlHead control adapter exception

Configuration files

The EPiServer settings in web.config now look a bit different. During the upgrade it seems the <applicationSettings> element got an empty xmlns attribute for some reason, resulting in an error saying Unrecognized attribute 'xmlns'. Removing the empty xmlns attribute solved the problem:

image