In this tutorial, you will be given a step-by-step guide of the process that I followed to upgrade Umbraco to v7. This guide contains a checklist that will walk you through all the steps you will need to undertake in order to perform a successful upgrade experience. The reason I'm writing this guide is that I recently had to upgrade a Umbraco website from version 7.5 to 7.7. I thought this upgrade was going to be a 30-minute job, however, 7 hours later I was still working on it. If you want to make your life as easy as possible when upgrading then read on.

Umbraco Upgrade PreInstallation Tasks

Before you upgrade any Umbraco site, there are a few tasks you need to do.

Your first task is to go to read the Umbraco Specific Upgrade page. This page lists all the breaking changes, config tweaks and settings that you will be required to make when upgrading. The page is available here. You might be tempted to skip this part, don't. Not applying the correct config will waste hours of your life. The steps on this page will be essential for you to upgrade error-free!

Your second task will be to ensure that you have your website correctly prepared for the upgrade. First, ensure that:

  • The existing site works
  • All code is committed into source control
  • Database backed up
  • Webroot backed up

Upgrading the site will involve config file updates and config changes. To ensure your upgrade goes smoothly, you will also need:

  • A file/folder diff tool, I use Beyond Compare
  • A vanilla Umbraco website installed that is on the version that you want to upgrade to. You can use this to dif the vanilla projects config files to your websites config files to see potential changes/issues

After you have all of these things, you are ready to begin.

How To Upgrade An Umbraco Website

Umbraco can be upgraded via NuGet, using Umbraco CMS. If your website doesn't implement the Umbraco Nuget package yet, I suggest you apply the Nuget package for your website's current version first. Ensure the site works after installing it and then attempt to upgrade.

Upgrading the Nuget package is easy. One thing to keeping mind when bumping the version numbers is that you want to apply the bump on your web solution, rather than on a project level. The reason for this is when you add packages to the solution it will apply them globally. If you only update the packages on some projects in your solution and not all of them, you can get consolidation errors, e.g. version mismatches between your projects. To apply a Nuget bump on a solution level, right-click on the solution in your Visual Studio solution, click 'Manage Nuget Packages Fro Solution'.

If things go OK, Nuget will add, remove, and edit a number of files. After the upgrade has run, you will need to build your project and then re-run your website. When re-running your site, you will be prompted to log in. After doing so, your Umbraco database will be upgraded in the background. If everything goes well, then your website might magically work. In reality, though, you will probably need to still do some configuration tweaks. On my last upgrade, the site still had a lot of issues at this point. If this happens to you, don't sweat it, it's expected.

Configuration Tweaks

Before applying these config tweaks, I usually add and commit the current state of the website into GIT into a new branch. It's easy to mess this step up. Having a method to quickly rollback will save you time.

This part of the upgrade process is where you follow the notes on the Umbraco upgrade page. My advice is to open up your diff tool and do a folder comparison between a blank vanilla website and your new upgrade files. Using the diff tool and the Umbraco upgrade notes, you should be able to see a list of files that are different. If you are new to Umbraco upgrades, then the main files that you will need to tweak are usually located in the config folder. The other main file will be the web.config file.

After making the changes that the upgrade page recommends, load your website and test it works. If it does, log into the Umbraco backend and ensure you can log in, you can open a page, make a minor page and save and publish that change. Ensure you can see the change published onto the front-end. Congratulations, you have now updated the site!

My Upgrade Walkthrough

On my last upgrade, I upgraded a website from Umbraco 7.5 to 7.7. As part of the upgrade, I copied the UmbracoMembershipProvider section from my vanilla Umbraco build into the web.config by accident This broke my membership provider which prevented me from logging into Umbraco. Following the notes, you need to ensure that useLegacyEncoding was set to false.

In my config folder, there were a number of config files that weren't needed anymore, so I removed config\autoNode.config, config\Combres.config and NodeRestrict.config

My big killer upgrade issue was down to dependency injection. A lot of people who use Umbraco don't write unit tests, or, follow SOLID principles as they write their code in the views. If you are in this camp I strongly suggest you look into using the Umbraco ModelsBuilder and route-hijacking. On my project I used StructureMap. In the 7.6 upgrades, one of the Umbraco core files expected the UmrbacoContext to be passed in. This completely broke my site, with this error:

`A public action method 'ysod' was not found on controller 'Umbraco.Web.Editors.BackOfficeController'.

This error was very specific to my site. I was able to find some more information about the error from Google. In the end, I followed the advice in this tutorial. This advice worked and my site loaded. After testing I was ready to deploy my code to the live website. At this stage don't forget to commit your updates to source control!

How To Deploy An Umbraco Website

To deploy your upgraded website, I suggest you follow a process similar to this. Create a backup of your newly upgraded database. Upload and install the upgraded database as a new database onto the production server. Do not touch the current live database. When publishing set your site to use the new database. If the upgrade fails, you can roll back quickly by changing a connection string. This is much simpler and adds a lot less stress compared to having to try and fix a broken database schema. I strongly advise you to follow this process when upgrading.

Next, you want to clear your live production files. DO NOT copy your upgraded files on top of the existing ones. This will break things. In my case, the TinyMCE rich-text editor didn't work until I cleared my webroot and did a fresh push. Also, ensure you have cleared all the temp files from the App\_data folder before deploying. If you do not do this, your website may behave unexpectedly.

After you have deployed, it's time to test your website and the Umbraco backend. When you're happy the site works, it's time to crack open a beer 🍻🍻🍻 Happy Coding 🤘