Upgrading Umbraco

With the newer versions of Umbraco Upgrading has gotten a lot better recently, it used to be the case that you would only upgrade if you absolutely had to. The Umbraco website has some pretty solid advice on the subject but I thought I would add in a few additional considerations that I have learned over the years.

Avoid third party Umbraco packages

This may seem extreme but I have lost count of the number of times a package has broken or worse caused serious issues when upgrading Umbraco.

It goes without saying that you should check package compatibility before performing any upgrade. Exceptions can be made if the plugin is from a known respected developer and is a frequently maintained and paid for piece of software. In that case you can at least expect fixes relatively quickly.

But generally if you need a plugin it is best to write your own so you have full control over the source and you can make any fixes that may be required as a result of an upgrade.

Use Nuget

Nuget is great for managing dependencies for you and using it to install and update Umbraco is now a relatively smooth process. If you have already added Umbraco into your solution using Nuget then it is straight forward to upgrade. You can either fire up the console and do an update or use the handy solution management tool to see exactly what versions are installed.

The benefit of using nuget is that you don't have to worry so much about dependencies between packages, it is not impossible to do this manually but it will be time consuming.

When doing the actually upgrade you will likely want to allow the config files to be overwritten so you can merge in any required changes. Just ensure you have everything backed up and ideally under source control before doing this! After the upgrade you will then need to merge your source control version back into the updated version to maintain your site specific settings. 

Keep Umbraco under Source Control

In the past I would not keep the main Umbraco and Umbraco Client folders under source control, the same with my bin directory files. My thinking was these are mostly managed and retrieved via nuget so keeping them under source control is overkill. However after a bad upgrade experience I tend to keep everything in source control so I can roll-back to a working version in an emergency. 

You can argue that nuget should be able to do this but it turns out its not always a guaranteed option. So to avoid ending up with a broken solution its best to have every thing your site requires under source control, if an upgrade goes south you can revert and try again.

Pay attention to the Breaking Changes

With every update of Umbraco there is a fairly concise release note put up on their site. In here there is section for breaking changes which is an essential read. Most of the time this is empty or relatively minor but especially the major version can have changes which could make an upgrade impossible or at least require more planning. 

Plan your deployment

Umbraco usually handles any database structure changes for you as part of the upgrade. This will happen if you update the code base and then run your site, Umbraco detects the version change and runs the upgrades as necessary.

If this happens on the production server then the IIS user will need modify rights on the web.config and the database user will need rights to make schema changes.

There are two ways to approach the upgrade process, you can either update the code base and deploy then let the upgrade run on your server. Or you can backup your live database, run the full upgrade locally against the backup and deploy everything including the database in one go.

The approach you choose will depend on how busy your site is and how much downtime you are willing to accept. Running locally has the advantage of catching any unforeseen issues and avoids the need to increase any permissions over what you ware comfortable with on the server.

Running locally has the downside that you will not be able to make any content changes between taking a database backup and deploying the updated version, unless of course you have good database compare tool like Redgate or dbGhost.

Always backup

This should be obvious but before doing any upgrade ensure you take a backup of the database and web root, if all else fails you can restore from the backups quickly.