Umbraco Upgrade Strategies

Traditionally in Umbraco, the perceived wisdom was that people didn’t upgrade their Umbraco sites. With the introduction of V7 however, there are many more compelling reasons to upgrade (nicer UI, it work on tablets, performance improvements etc.) In this article I’m going to talk a little bit about upgrading Umbraco, and some of the strategies and pitfalls you might encounter!

Why upgrade?

In the last 6 months, I (and many of my clients) have been asked to upgrade various Umbraco sites, sometimes to the end of the V6 branch, and more recently from V4/6 to V7. There have been various reasons for the upgrades:

• Bug Fixing (we’ve hit a bug that’s become an issue, and the bug is fixed in a later release).

• Mandated by client IT/Security, I’m “lucky” enough to work with a few very large companies, and sometimes these companies have IT/Security policies that mandate how up to date their software must be.

• The client prefers the UI of V7.

• My client (the agency) has a staff of developers who all hate XSLT, and they want to standardize all their legacy sites on Razor, as it makes it easier for them to work on.

Whatever your reasons are, make sure you’re upgrading for a good reason, and not just for the sake of it. Depending on the size and complexity of the site, and how many versions you’re upgrading, it can be a hefty job.

Upgrade, or Rebuild?

An example of this is a site I’ve worked on is where the original developers used dozens of custom DataTypes, and stuck a ton of 3rd party dependencies on the top (nHibernate on top of the XSLT cache, because that’ll be faster, right?) and generally built the site in such a way that even the developers don’t know how the back office works properly. Only a crazy person would try and upgrade that site (OK, I’ll admit it, I tried to upgrade that site, bad things happened, I don’t want to talk about it).

How do you upgrade?

If you’re updating from older versions all the way to 7.3 (or higher), then there’s some good news! The Umbraco core team put some serious work into the upgrader, and in theory you can jump all the way from 4.7.2 to 7.3 (I say in theory, I’ve actually done this on a relatively simple site, and it does indeed work, your mileage may vary, depending on the complexity of the site).

For single version updates, just follow the upgrade advice on the release page. Here’s an example of the release page for 7.3: https://our.umbraco.org/contribute/releases/730/

If you’re using Visual Studio and NuGet, you can use the NuGet package manager for the upgrades, and that’s my preferred method. Otherwise, you have to do it manually, which is much more time consuming. A manual update involves copying some folders into your site and then merging back in your changes to the site config files.

When updating older versions of Umbraco, you may need to step through several versions to get to the version you want (say you’re updating to the end of v6 for example). This is one of those things that’s not super well documented, so Google is your friend here, see what others have done! A fantastic resource for this is Lee Kelleher’s archive of older Umbraco versions, which also has the recommended minimum versions you need to install to get all the way from V2 to V7. You can find this wonderful page here: http://code.leekelleher.com/umbraco/archive/.

Read up on the general Umbraco upgrade page for some useful information on upgrading: https://our.umbraco.org/documentation/getting-started/setup/upgrading/general

Common upgrade woes

Here are a few common issues that I’ve seen when upgrading Umbraco, and how you can fix them!

• DLL reference hell – one plugin references one version of a DLL, and the new Umbraco version wants a different one. You’ll need to add assembly binding redirects, or upgrade the conflicting plugins.

• File permissions – make sure Umbraco has the correct permissions.

• Database permissions – if the database user can’t modify tables and indexes, you’ll get a database update error when you run the updater.

• Not deleting older DLLs – some versions of Umbraco require you to delete older DLLs.

• Old files being cached by Chrome – clear your cache before firing up the site to finish the upgrade.

• Plugin Stops Working – check for an updated version of the plugin, remove it (if no longer needed) or rewrite it yourself.

• If your old site had dashes in the DocType or Template aliases, you’ll have issues running the site. You’ll need to re-save the affected items and re-publish your site.

• Browser Cache – on V7+ sites, Google’s overly aggressive caching can cause some issues, clear your browser cache before running the upgraded site.

• Pre-update indexes – sometimes old data can be cached in the Examine indexes, clear all of your Examine Indexes in App_Data/Temp and restart the App Pool.

It's all in the planning

I cannot stress enough how important it is to plan your upgrade. Spending a bit of time up front can save you a TON of time later on. Here are some things you can do in advance, to help save time later:

• Audit all of the DataTypes used on the site, are they all supported in the version you’re upgrading to?

• If they aren’t, see if there’s an updated version you can swap to, or a built on one that’s the equivalent

• If you find replacements, plan how to reformat the data that’s saved in the properties if you need to change it (you’ll probably have to do this yourself using the API)

• Audit all of the Plugins that are installed on the site and check they’re supported on the version you’re upgrading to

• If they aren’t, you’ll have to either find replacements, or rewrite them yourself

• Check that the servers you host on support the latest versions of .Net, and are running a relatively modern version of IIS

• Google the upgrade path you’re trying and see if anyone has blogged about it, the chances are someone has, and you may pick up some valuable intel on issues you might encounter

• Check the Umbraco Upgrade page for any version specific steps you may need to take: https://our.umbraco.org/Documentation/Getting-Started/Setup/Upgrading/

For most average sized sites, this process should only take a few hours, but it’s well worth the effort, as it gives you something to work towards, and gives you a handy list of things to test.

Doing the upgrade

Before you upgrade, back up your site files and your database. If you’re upgrading through multiple steps, back up at every single hop, that way you can roll back to a specific version if you need to work out when something broke.

One thing to note, some versions have specific upgrade notes, such as DLLs that must be removed etc. Some of these only apply to manual updates, but always check on the Umbraco release page for the version you are upgrading to, to see any version specific advice.

If you’re using Visual Studio and NuGet, run the NuGet Update command on the Umbraco Package, then merge your config files (remembering to leave the umbracoVersion in web.config at the previous version). Fire up the site, and follow the on screen update instructions to apply the update. Once done, you should hopefully have a working upgraded site. If you don’t, time to get all Sherlock Holmes and figure out what’s broken and why!

If you’re doing it manually, you’re in for a bit more work. Grab the zip file of the version you’re updating to, and copy the /bin, /Umbraco,  /Umbraco_Client, and config folders into your site.  Next, take the backed up config files from the old site and merge your stuff into the new ones (I use WinMerge for this, but you can use any decent merge tool).

When merging config files, here are the ones you need to check (for both upgrade methods):

• /config
• /umbraco/config
• web.config

Again, once you’re done, run the site, and you should see the upgrade screen and you get to follow the instructions. Hopefully you’ll be good, but if not, time for you to do some debugging.

If you’re stepping through multiple versions, rinse and repeat until you reach your desired version!

In Conclusion

Upgrading your Umbraco site to the latest version has certainly got a lot easier with the release of V7.3 (I’m just polishing off an upgrade straight from 4.7.2 to 7.3 at the moment). It’s definitely not quite the laborious process that it used to be. One caveat on all this that I’ve found is that the simpler your Umbraco installation is, the easier it is to upgrade. If your site has a ton of 3rd party dependencies, or you use Code First or something like that, you may find that upgrade a little more painful! In general though, as long as you plan your upgrade carefully, and make sure you take plenty of backups, you should be fine!

As always with Umbraco, the community is your friend. If you’re not sure about upgrading, or you have any questions, ask a question on the Forums, or on Twitter.