In today's guide, I'm going to walk through the process of upgrading Umbraco from version 6.2 to 7.5. The aim of this post is to try and explain the issues you might encounter when upgrading and, hopefully, shed some light on some of the architectural choices available to you that can help make upgrades as painless as possible, moving forwards. Unlike some other CMS systems (like Sitecore) upgrading Umbraco is usually pretty painless if you follow the right steps.
Adding new functionality is always going to be more appealing to a business than spending time on an upgrade that can introduce a lot of risk and uncertainty. In 90% of the upgrades I've worked on, the catalyst for an upgrade is usually something is not working as expected and this was no different:
- The site was so old it was built using a Visual Studio website for the project type (not web application)> The site did work, but it meant the developers weren't able to take advantage of future upgrades via Nuget, or able to use transforms for the continuous integration process.
- The site was struggling to invalidate the cache correctly when configured in a load-balanced environment, With the release of 7.3 improvements were made to the way Umbraco works in a clustered environment (more information can be found here) so my recommendation was to spend a day upgrading the site to make life easier moving forward.
Converting The Website To Web Application
This step was the one that I was quietly dreading, but I had the site up and running in less than an hour. In this step, all I did was upgrade my website to a web application with Umbraco installed by Nuget. Doing this was pretty simple, I created a new web application called 'Website.Web' and via Nuget I installed the same version of Umbraco the site uses. Next, I copied the webroot of the existing 6.2 websites on top of the web application version. In Visual Studio I then excluded the 'bin' folder, 'install' folder and'obj' folder: I built the solution and loaded the website in a browser and everything worked as expected. I was fortunate that none of the website's custom code complained at all, everything just worked. The next step was to get as much of the site assemblies to be referenced from Nuget instead of through a file in the 'bin' folder. To do this I went through the sites 'bin' folder and removed any assembly that I could add using Nuget, for each assembly, I deleted the file from the 'bin' folder, added it via Nuget, re-built the site and ran it to make sure it worked. This next step isn't something you have to do to upgrade your website, but it did make upgrading the site super easy... getting transforms working. One of the aims of the project was to have a robust continuous integration process. The way the site had been originally set-up meant that testing things like the live version involved manual changes. When the 'live' version was deployed, the web.config would get overridden using a custom tool. This solution was bespoke to this company so I won't go into too much detail as it's really not important for anyone else trying to upgrade. The important part is that moving forward, each environment would be configured by its own transform files. When you try and upgrade Umbraco via Nuget, the installer will attempt to override the web.config and several of the files in the 'config' folder. By taking advantage of transforms, you can try and offload as much of your custom settings into custom config files that won't be affected by the upgrade installer. These transform files won't be overridden by the upgrade and if you have your transforms configured correctly, you can completely override your web.config with the latest stock version and your website will still work afterward. This step, in essence, makes upgrading really simple. Instead of having a lot of custom bespoke changes in the config files that need to be merged using a diff tool, like Beyond Compare, you just build the project with Visual Studio and SlowCheeta and the correct settings are copied on top.
Upgrading to version 7
After I had the site building and running from a web application, the next step was to upgrade Umbraco via NuGet: Before I tried to load the site, I followed the advice from Umbraco HQ, you also need to delete these files:
- Delete /bin/Our.Umbraco/uGoLive.47x.dll
- Delete /bin/Our.Umbraco/uGoLive.checks.dll
- Delete /bin/Our.Umbraco/uGoLive.dll
- Delete /Config/xsltExtensions.config
As I mentioned in my transform section above, as I had all my custom Umbraco settings like connection strings, app setting etc.. injected via transforms and not within the web.config itself, I could override my existing web.config and 'config' folder files with the stock 7.5 versions build the solution and the site worked as expected. Using this approach I did have a few issues with binding redirects. As I used this approach to make sure the site was using 7.5 config files, I download 7.5 from here. I copied the below files everything from the blank 7.5 zip files on top of my project
- All file in the /Config folder
Before you try to load the website, I should point out that I did bump into a few issues here. First, if you have Umbraco packages installed on your website installed through Umbraco, like uSync, I found it a lot easier to uninstall those packages before you upgrade and re-install them afterward. The first time I tried to upgrade the website without doing this, uSync, in particular, crashed the upgrade process. After rolling back the website, I uninstalled uSync and Contour (which only had one basic form) before attempting to upgrade again. With async uninstalled, the installer ran through in a few minutes. This made the process a lot easier. After I upgraded successfully I re-installed my packages and everything worked as expected. When I tried first tried to load the site, I saw this error:
Server Error in '/' Application.
Could not load file or assembly 'MySql.Data' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.
Exception Details: System.IO.FileLoadException: Could not load file or assembly 'MySql.Data' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)
Looking at the logs in 'App_data' -> 'Logs', I could also see this expcetion:
System.IO.FileLoadException: Could not load file or assembly 'MySql.Data, Version=126.96.36.199, Culture=neutral, PublicKeyToken=c5687fc88969c44d' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)
The issue was with the site getting confused about which version of 'MySql.Data' it should be using. The site was using 188.8.131.52 but the binding redirects were incorrectly configured. To get around this, instead of trying to manually update the web.config, I simply re-installed the MySql.Data package in the Nuget console window:
Update-Package –reinstall mysql.data
Doing this fixed the issue and meant the upgrade will load.
After adding in my username and password and click 'Next', the installer should upgrade the database for you. If everything goes successfully, 7.5 should load correctly.
Upgrading Umbraco is pretty painless and I managed to get the Site up and running in less than 2 hours. Enjoy!