I was about to do an upgrade of an EPiServer CMS 4.61 site to CMS 6. These are the steps I calculate on being necessary to perform:
- Upgrade to 4.62
- Upgrade to 5.2.375.7 or more commonly known as the EPiServer CMS 5 R2
- After that is done upgrade to EPiServer CMS 5 R2 SP2 , to prepare for an upgrade to CMS 6
- Finally upgrade to EPiServer CMS 6
In between these steps I guess that the biggest API change will be between step one and two. It is also between these two steps that I’ll see the biggest affect on my applications code. The following steps won’t be that much hassle, at least I guess.
My setup is a Macbook pro 15’’ running Windows 7 x64. I have EPiServer deployment center installed, but not all versions only the latest one. I’m also running a local SQL 2008 Express and planning to run the sites on my local IIS 7.5.
So lets start!
Step 1: Upgrade to 4.62
This step requires the EPiServer Manager, found at http://world.episerver.com. You also need to have the correct version packages so that upgrades are possible.
I really thought that this step would be with out problems, i.e. moving up to the next version, but I was wrong. The problem that I encountered was that it complained on the UNC-path, which it said that it required a path similar to \\server\path.
Although I found a very good tip on EPiServer World that I made use of instead. So instead of trying to find the error I did run the SQL-scripts manually and then copied the new files. It all seems to be working fine.
This was the exception message:
1: System.ArgumentException: UNC-sökvägen måste ha formatet \\server\resurs.
2: vid System.IO.Path.NormalizePathFast(String path, Boolean fullCheck)
3: vid System.IO.Path.NormalizePath(String path, Boolean fullCheck)
4: vid System.IO.Path.GetFullPathInternal(String path)
5: vid System.IO.Path.GetFullPath(String path)
6: vid System.Diagnostics.FileVersionInfo.GetFullPathWithAssert(String fileName)
7: vid System.Diagnostics.FileVersionInfo.GetVersionInfo(String fileName)
8: vid EPiServer.Install.InstallPackageManager.CreateLocalProduct(Product derivedProduct, String rootPath, String masterFile)
9: vid EPiServer.Install.InstallPackageManager.CreateMasterProduct(String rootPath)
10: vid EPiServerManager.SetupConfiguration.get_MasterProduct()
11: vid EPiServerManager.Components.LicenseValidation.TestLicense(SetupConfiguration wizardInstallConfiguration)
Step 2: Upgrade to EPiServer CMS 5 R2
Next step is to upgrade the site to EPiServer CMS 5 R2, but before that I’ll need an empty site of that version. This version of EPiServer is using a different installation tool, the EPiServer Deployment Center. So this is the first step to make. I already had it installed, but I need the packages for CMS 5 R2, which could be found on EPiServer World.
This was the point during which I encountered my second obstacle. That package version is obviously not supporting Windows 7, which made me a little bit confused. See the error message below in the image.
Handy as we are, I did a small workaround together with my colleague Thomas. We found a small tool called Orca (can be downloaded here, but notice that is is done on you own risk ). Previously supported and developed by Microsoft. This tool is a MSI editor, that enables me to change some meta information in the MSI-package. I looked for the error message and found a property named: InstallExecuteSequence. One parameter in that property named: CA_Err_UnsupportedOSVersion contained some suspicious information.
So I decided to remove the whole row, marked in the image above.
After doing this and saving the MSI-package the installation worked as a charm! Okay this is not totally by the book, but I had to to get on with my project. I wish this could’ve just been working from the start.
Install a new EPiServer CMS 5 R2 site
Once the installation of the EPiServer Deployment Center was complete I started an installation of a clean site. To find out more how this is done, read this post on installation instruction of an EPiServer CMS 5 R2 site on EPiServer World.
When my site started, which it does automatically once the installation is complete. I got a very strange error that my IIS 6.1 is giving me. It said the following:
1: HTTP Error 500.0 - Internal Server Error
2: Unable to call LoadLibraryEx the ISAPI filter (in Swedish: Det gick inte att anropa LoadLibraryEx på ISAPI-filter)
3: C:\Windows\Microsoft.NET\Framework\v4.0.30319\aspnet_filter.dll
This is something I knew the solution to. I looked on the newly generated Application Pool under the Advanced Settings (found by right-clicking on the application pool in the IIS Manager). Here I found a property called “Enable 32-Bit Application” that was set to false. Set this to True and it should work, at least it was the solution for me. The reason for this is that IIS is running in 64-bit mode but the application is 32-bit.
Now finally I saw this familiar and friendly page:
Start the Migration process
For this step I needed the EPiServer Migration Tool, that can also be found on EPiServer World. You’ll need to navigate to downloads and select the right CMS version 4.62 then you’ll find this tool as well.
I started the migration process by adding the paths to my web.config files. The old one in website 4 and the target in website 5.
After this step you’ll get a confirmation that you want to use the database of the original site.
Attention: Make sure that you make a backup of that one before proceeding!
Following steps are to define what properties that should be migrated and converted to XHtml instead of a Longstring value.
Finally confirm that you want to proceed .
Another exception occurred thrown by EPiServer.Migration.LanguageSetting.GetLanguageIds()
This is how it looked for me. I got a strange feeling about this, something told me that I had experience this before. The site that I’m trying to migrate contains quite a lot of LanguageBranches. Something tells me that one of these has changed between these two versions.
After some research, yes of the binaries in the Migration Tool, I found out that the method GetLanguageIds() do not do that much! What could cause the problem is the fact that the database object is still null after instantiation in the method.
After some further research I found out that the instantiation method is of course using the web4.config file to get hold of the database. It is using the connectionString, which in my web.config was missing! Since this is not necessary in EPiServer CMS 4.6 it has never been added. The CMS is using its own property EPsConnection and that was obviously what the Migration tool was using at the beginning of the wizard as well. Since I got a confirmation on what database to use.
Still I found the solution and now we reached this nice step:
Of course there are a few language codes that has changed. In my case Danish and Chinese. So these needs to be remapped, but that is fortunately something that the tool offers support for.
Now, lets start the migration
Well it seems to be going well, until it ended prematurely again and it said that EPiServer.XForms requires a certain version of the log4net.dll. I checked in the bin-folder and it seems alright. I realized that his might need to be installed in the GAC to work and so I did. Guess what, that did the trick.
Note: to install a binary-file manually use the Gacutil. For more instructions on that read about the Gacutil on msdn.
Step 3 & 4: Upgrade to EPiServer CMS 6 via 5 R2 SP2
This was all about using the EPiServer Deployment Center and upgrading the site. Actually these steps were really easy! No real problems.
Step 5: Update code
Now lets start with the fun part, but this is a separate story.
Some other great resources and help on the way
- EPiNova has written two great step-by-step guides on how to migrate, read them and you definitely are a master of the basics.