How to upgrade Umbraco safely

Posted written by Paul Seal on April 17, 2018 Umbraco

I have upgraded quite a few Umbraco sites recently and I thought I would share my experience and strategy with you to help you do your upgrades as safely as possible.

Before we start

You need to make sure your code is checked into source control. If you don't have your code in source control yet, shame on you. There are lots of options for source control. I prefer to use GitHub myself.

Create a new branch to perform this upgrade on.

Back up the database. I like to use SQL Server for my databases, so I create a .bak file to get a snapshot in time before starting the upgrade.

If you are using Umbraco Cloud, you don't need to worry about any of this because they sort out all of the upgrades for you.

What not to do

When first trying to run the upgrades, I tried to go from the current version directly to the latest version. I always ran into errors when doing it this way and it always caused me issues.

My upgrade strategy

Don't upgrade all in one go, because that never works, see above

Make sure you login to umbraco before running an upgrade. I found that I couldn't login during upgrading a few times, but when I was already logged in, I was able to authorize the upgrade and it worked fine after that.

Check in your code to the branch before every upgrade step

Take a backup of your database before every upgrade step

Run the upgrade using NuGet Package Manager in Visual Studio and choose a specific version each time

1
2

When you upgrade, accept all config changes and then compare the changes of all the config files using your source control diff viewer. That way you can see and control exactly which settings are changed.

When the upgrade has finished in Visual Studio, you need to Rebuild. Then go to http://yourdomain/umbraco to get it to do the database migration.

To get to version 7.2.0 you should follow this version specific guide.

Once you get to version 7.2.0, the database migration steps are taken care of for you, so you can get into more of a rhythm.

Upgrade path from 7.2.0 to 7.5.14

Remember to check in and back up between each step, also remember to login to Umbraco before upgrading each time.

Notice I take it to the last version of that minor release each time. You can see a full list of releases here.

7.2.0 => 7.2.8

7.2.8 => 7.3.8

7.3.8 => 7.4.3

7.4.3 => 7.5.14

Every time I do an upgrade step, I have a habit of republishing the whole site and rebuilding the indexes. I don't know if it makes any difference, but it feels like it helps.

A note about 7.6

When upgrading to 7.6 and above, you will get a new setting in the file umbracoSettings.config which says:

<!-- Enables value converters for all built in property editors so that they return strongly typed object, recommended for use with Models Builder -->
<EnablePropertyValueConverters>true</EnablePropertyValueConverters>

This setting can break your site if you don't change your code. It changes how you get the values from your content items, media and members. You can change your code to use these property value converters, but if you don't want to change your code, you can set this property to false. Be aware that every upgrade after this will turn the property back on, so you have to keep changing it back each time.

What if you need to use the old datatypes?

There is another setting which you can add in the umbracoSettings.config file to allow you to continue to use the old datatypes when creating or editing them. They will show up in the datatype dropdown and will have (obsolete) in their name. To enable this, put this setting under the enablePropertyValueConverters setting.

<showDeprecatedPropertyEditors>true</showDeprecatedPropertyEditors>

In the main web.config file there is a setting called useLegacyEncoding which is on the UmbracoMembershipProvider. When doing an upgrade from a version lower that 7.6 you should ensure useLegacyEncoding is set to true.

Upgrade path from 7.5.14 to 7.10.4 and above

7.5.14 => 7.6.13

7.6.13 => 7.7.13

7.7.13 => 7.9.6

7.9.6 => 7.10.4

7.10.4 => 7.11.1

Repeat this cycle of backing up, checking in upgrading, diffing etc.

This is not a difinitive answer and you may be able to upgrade in bigger chunks than this. I just wanted to share with you the strategy which I developed that had the least errors.

Good luck with your upgrades. I hope it goes well for you.