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:
The upgrade wizard is fairly straightforward, and once completed you should see some new version numbers among the assembly redirects in web.config:
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:
Once the process is complete…
…you’ll notice updated files in the Modules app data folder and the modulesbin folder in your web root:
Upgrade NuGet packages
Next ensure you have up-to-date EPiServer NuGet packages:
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!):
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).
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):
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:
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:
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:
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:
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:
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.
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:
This assumes you use the [appDataPath] placeholder in your VPP folder path settings:
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…
…you’ll get an exception saying “Could not load type EPiServer.UI.WebControls.ControlAdapters.HtmlHeadAdapter”:
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:
