Upgrading to EPiServer 7.5 - without the headache

Earlier today I managed to transform the day from huge #FAIL (with headache) to the good feeling of #SUCCESS (headache gone). Oh, this is not twitter. Sorry, I forgot. 

The project I'm involved in currently, we develop an application with EPiServer 7 (it's actually 7.1 to be precise) and I personally enjoy the product being a lot more testable than ever before. Stay tuned for an upcoming post on test driven development with EPiServer. (and there goes the holidays ... why did I promise that?).

The latest version - 7.5 - was recently released and since we are at the beginning of the project there cannot be a better opportunity for an upgrade. So, we made the decision to at least give it a try.

There is an upgrade guide at the EPiServer World site, but I guess there are a couple of scenarios that the team over there did not try out. I have sent them feedback on this and some issues raised here will probably be solved shortly.

Have a look at the upgrade guide.

I suggest that you follow the upgrade guide along with the stuff I describe here. 

Before you start, I recommend that you take a copy of the database and use the copy when upgrading (don't forget to update the connectionstrings configuration file). 

The first impediment I ran into was that the installer failed because the site was using a VPP folder in an external share. Before you run the installer, copy the VPP folder to your local disk and update the episerverframework configuration file.

If you would wake up in the middle of the night and realize upgrading was a bad move, all you need to do is a rollback of the source code. You only messed up the copy of the database and the local VPP folder. Don't worry.

Follow the steps 1-9 in the guide.

The following step in the guide is about updating the assembly references. Here is a bug. In our project we have added the assemblies from the EPiServer NuGet feed and to update without the headache this what one need to do: right click the references folder, select "Manage NuGet packages" and navigate to the Installed packages folder. Uninstall the references to "EPiServer.CMS.Core" and "EPiServer.Search".

Next up is where I found the bug: when I browsed the new assemblies in the EPiServer feed and installed them, the reference to StructureMap had the wrong version and the code would not compile. What I did was to install StructureMap from the official NuGet feed first. Then I went back to the EPiServer NuGet feed and installed "EPiServer.CMS.Core" and "EPiServer.Search". The previously installed version of StructureMap was already there and was not overwritten.

Here is the version existing in the EPiServer NuGet feed.

Here is the newer version from the official NuGet feed.

The solution is ready to be built. Most likely the compilation will fail, because of the breaking changes of the 7.5 version. Step 12 in the guide is about making the source code changes.

One thing that I find confusing is the code existing in the EPiServer.UI assembly. We have written a custom report in this project and that needed to be updated. The new stuff to use is within the namespace EPiServer.Shell, but the actual assembly is EPiServer.UI. And that assembly isn't referenced when getting the stuff from the EPiServer NuGet feed. So, what did I do? Well, I picked up the local dll from the EPiServer installation folder (the 7.5 folder).

Confusing, isn't it?

Finally, the code actually compiles without any errors. Tadaa!

But wait. Don't browse the site! I did that. And it lead me to the wrong problem solving path. Headache. The site should actually not be browsable at this point, and that is fine. So, move on to the next step in the guide and run the update add-ons stuff from the Deployment Center.

By now, the upgrade is almost done. So close, and yet so far away. The next move is to migrate the VPP files into the new media system. The guide mentions the VPP Migration Tool. But where is it? Guys, a link to the download page from the guide would save us lots of time (and headache). Finally I found the tool at the download page for the CMS 7.5 page (the column to the right with the header "You might also want to download"). 

Almost done. Don't give up! Have a banana and drink some water.

It's time to follow another guide: Migrating VPP-based files to the new media system.

I added the classes GenericMedia, ImageFile and VideoFile. I still am not sure if that really was needed. The guide describes the code as just examples. To be safe I also regenerated the GUIDs with some help from Visual Studio.

The final impediment is the kind of problem that is so simple, but sometimes so difficult to see. I think it's about that tree and the forest, you know? The Migration Tool threw an exception when I tried to connect to the site. The exception was about not being allowed to use external assemblies. "What? Where? Who?"

Man, did I google to find a solution. Whew!

The executable file itself was blocked by Windows since it was a downloaded file. By right clicking it and selecting properties, the "Unblock" button will appear. Click it. Just do it. Run the Migration Tool again and you will finally be able to tweet #SUCCESS.

The things described here has been verified in two different virtual machines, one with Windows Server 2012 R2 and the other one with Windows 8.1 Pro.

Good night.