«
»

Yet another… How to upgrade to EPiServer 7.5

February 9th, 2014

I struggled with the upgrading from EPiServer CMS 7.1 to EPiServer 7.5, even if there are several good blog posts about this already (Ted & Gustaf, David Vujic) it seems everyone comes up with new obstacles so I thought I’d share my step-by-step guide. 

I strongly suggest you read the documentation from EpiServer on how to upgrade, the breaking changes in EPiServer 7.5, migrating VPP based files and other related documentation before following these steps.

  1. Take a backup of the database, all files in the project, the VPP folder and packages folder. Note that your .config files and database will be modified by the upgrade tools.
  2. If you store the VPP files on a Network share, copy it to the local computer and change the AppData path in EPiServerFramework.config.
  3. Download and install EPiServer 7.5 from EpiServer World.
  4. Download (but don’t install yet) the VPP Migration Tool, linked at the right side of the download EPiServer 7.5 page.
  5. Upgrade the website using Deployment Center to EPiServer 7.5. Choose the option “Upgrade site with SQL Server database“. You will have the possibility of also upgrading related components which need to be upgraded, such as EpiServer Search.
  6. After the upgrade, run the “Upgrade/disable Add-ons After Product Update” on the project as well.
  7. Install structuremap (v2.6.4.1) from NuGet. You probably have v2.6.1.0 before doing so.(This is to avoid the error: Error 97 Assembly ‘EPiServer.Framework, Version=7.5.1000.0, Culture=neutral, PublicKeyToken=8fe83dea738b45b7′ uses ‘StructureMap, Version=2.6.4.0, Culture=neutral, PublicKeyToken=e60ad81abae3c223′ which has a higher version than referenced assembly ‘StructureMap, Version=2.6.1.0, Culture=neutral, PublicKeyToken=e60ad81abae3c223′ c:\EPiServer\Sites\packages\EPiServer.Framework.7.5.1000.0\lib\net40\EPiServer.Framework.dll)
  8. Make sure that the latest NuGet packages for EPiServer 7.5 are installed: EPiServer.CMS.Core (v7.5…) and EPiServer.CMS.UI (v7.5…)
  9. Delete the reference to EpiServer.WebDav if it’s still referenced in the project.
  10. Create a folder called “Media” in the Models folder and add the following two classes used to hold data for all files which will be migrated from the VPP folders:
    ?Download GenericMedia.cs
    1
2
3
4
5

    [ContentType(GUID = "1A615570-06AC-4148-873E-7121D3FBC7EB")]
public class GenericMedia : MediaData
{
    public virtual string Description { get; set; }
}
    ?Download ImageFile.cs
    1
2
3
4
5
6
7

    [ContentType(GUID = "224BB751-1A90-432F-80D8-D685943439B2")]
[MediaDescriptor(ExtensionString = "jpg,jpeg,jpe,gif,bmp,png")]
public class ImageFile : ImageData
{
    public virtual string Description { get; set; }
    public virtual string AltText { get; set; }
}

    Of course, you should specify the properties you need. These are just examples but will do in most cases.
    If editors should be able to upload video files too, then you should create a model for that as well:

    ?Download VideoFile.cs
    1
2
3
4
5
6

    [ContentType(GUID = "21B5145B-D90E-4B67-BF5D-00196F5A7FCE")]
[MediaDescriptor(ExtensionString = "flv,mp4,mov,avi,webm")]
public class VideoFile : VideoData
{
    public virtual string Description { get; set; }
}
  11. Now compile and correct the errors you encounter. Below are some examples of errors which might show up and how to fix them.
    ?View Code TEXT
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

    Remove all: using EPiServer.DataAbstraction.PageTypeAvailability;
 
Change: AvailablePageTypes to AvailableContentTypes
 
Add the following USING on all classes where you're using Availability.None:
using EPiServer.DataAbstraction;
 
Change: PageEditing.GetPageIsInEditMode() to
PageEditing.PageIsInEditMode
 
Change: EPiServer.Configuration.Settings.SiteUrl to
EPiServer.Web.SiteDefinition.Current.SiteUrl
 
Change: EPiServer.Configuration.Settings.Instance.SiteDisplayName to
EPiServer.Web.SiteDefinition.Current.Name
 
Change: PageProviderCapabilities to ContentProviderCapabilities
 
If you add a ContentArea anywhere, then change:
contentArea.Add(currentContent);
...to...
contentArea.Items.Add(new ContentAreaItem { ContentLink = currentContent.ContentLink });
 
Change: UIHint.Document to UIHint.MediaFile
 
Change EPiServer.Web.Routing.UrlResolver.GetVirtualPath() to
EPiServer.Web.Routing.UrlResolver.GetUrl()
  12. When the project compiles without any errors, make sure the website is up and running, no files are opened in Visual Studio and soon we’re going to migrate the VPP files using the VppMigrationTool.
    Before you run the migration tool, you need to make sure it will run with proper rights. If you have Windows 8, make sure the .exe file isn’t blocked by editing the file properties and clicking “Unblock“.
    We also need to edit the file VppMigrationTool.exe.config in a text editor and insert the following line inside the CONFIGURATION node, but outside of the STARTUP node:

    ?View Code XML
    1

    <runtime><loadFromRemoteSources enabled="true"/></runtime>

    This is to avoid the error:
    Could not load file or assembly EPiServer7.5VppMigrationTool\VppMigrationTool.exe or one of its dependencies

  13. Now run the Vpp Migration Tool. Choose the proper path to the website root, and click “Connect”.
    Choose the VPP folders which should be migrated, and then click “MIGRATE”.
    After the migration is done, check that the website is functional and that the files are migrated. If all is fine, you can delete the VPP folders you chose to migrate.
  14. If necessary, transfer the changes made to the .config files to any build script versions or similar.

You should be done now! =)

Unless…

  • If you’ve used PageObjectManager for storing data, you should change the implementation into using DynamicDataStoreFactory instead. See EPiServer documentation for more information.
    PageObjectManager still works but will be removed completely within a near future according to EPiServer.
  • If you have code which reads or writes directly to the VPP file system, for instance by using the HostingEnvironment.VirtualPathProvider or UnifiedDirectory.GetPageDirectory you need to change the implementation of those parts. Check these links for more info: [1, 2, 3, 4, 5, 6]
  • If you’re using ImageResizer in the project, the integration is now broken. But there is a workaround here.

This entry was posted on Sunday, February 9th, 2014 and is filed under Uncategorized. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

Leave a Reply