In this post, you will be given a step-by-step guide of the process I use to upgrade Umbraco.  This guide contains a checklist that will walk you through all the steps that you will need to follow to ensure a successful experience. 

The reason I'm writing this guide is because I recently had to upgrade an Umbraco website from version 7.5 to 7.7.  I thought this upgrade was going to be a 30 minute job, 7 hours later I was just completing 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 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 may need to do. The page is available here. You might be tempted to skip this part, don't. Skipping it will waste hours of your life. The steps in this page will be essential for you to upgrade.

Your second task will be to ensure you have your PC correctly prepared for the upgrade with all the right tools installed. 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 to the version you want to upgrade to. You can use this to compare the config files to your website, 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 installed via Nuget which I suggest you use to upgrade your site. If your website doesn't use Nuget yet, I suggest you apply the Nuget package for your website's current version, ensure it works and then attempt to upgrade.

Upgrading the Nuget package is easy. You want to use Nuget 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 try and install packages on a local level, you can get consolidation errors, e.g. version mismatches between your projects. To use Nuget get on the solution, right-click on the solution in your Visual Studio solution, 'Manage Nuget Packages Fro Solution'.

If things go OK, Nuget will add and remove, edit and add and remove a number of files.  After the upgrade has run, you will need to update to re-run your website.  You should 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.

Configuration Tweaks

Before applying these config tweaks, I usually commit my changes/back them up. It's easy to mess this bit up and having a quick rollback will save you time. On my last upgrade, the site still had a lot of issues at this point. If this happens to you, don't sweat, it's expected.

This part of the upgrade process is where you follow the notes in the Umbraco upgrade page. My advice is to open up your diff tool and do a folder compare 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 upgrades, then the main files that you will need to tweak are usually in the 'config' folder. The other main file will be your web.config file. I advise you use your diff tool to compare these things closely

After making your changes, 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.

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 onto my 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 issue was down to dependency injection. A lot of people who use Umbraco don't write unit tests, or follow SOLID principles. If you are in this camp I strongly suggest you look into it. On my project I used StructureMap. In the 7.6 upgrade, one of the Umbraco core files, expected the UmrbacoContext to be passed in. This completely broke my site, with this error:

Urlhttp://umbraco/umbraco/ysod A public action method 'ysod' was not found on controller 'Umbraco.Web.Editors.BackOfficeController'.

This error was very specific to my site. The long and short is that I was able to find some more information about the error from Google. In the end, I followed the advice in this tutorial,  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.  Do not delete the existing database.  Instead, upload and install the upgraded database as a new database onto the production server.  Now if my upgrade fails, I can roll back quickly by changing a connection string, rather than 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 one.  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.  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 ;)