Upgrading Umbraco

I was recently asked to upgrade the second ever Umbraco site I built from 4.0, all the way up to 6.1.6 (if possible). I was expecting the process to be quite painful, as they used a lot of old legacy DataTypes and packages (to be expected with the age of the site), but I was actually pleasantly surprised that performing the upgrade went pretty smoothly. It's just a bit time consuming!

I erred on the side of caution, and stepped through several versions to get from A to B. You could probably get away with less versions, but I wanted to play it safe! The versions I jumped through were:

• 4.5
• 4.6.1
• 4.8
• 4.9
• 4.11.4
• 4.11.10
• 6.0.5
• 6.1.6

Before you get started, I would recommend downloading the excellent WinMerge (or similar). A decent merge tool will make the upgrade process so much easier! Also read up on the general Umbraco upgrade advice, and the version specific upgrade advice. You can also check the release notes for each version you step through, as they sometimes have additional useful information in. These can be reached from the downloads page on our.

Make sure that you take a database backup at every step of the way, and a backup of the site files (I put everything into source control so I can step back to different versions if need be, and checked in after each successful upgrade).

For most versions, the process is the same, copy the "/bin", "/umbraco_client" and "/install" folders from the updated version into your site. Then copy everything in the "/umbraco" folder EXCEPT for the "/config" folder. Next, fire up WinMerge, and merge the following folders and files from the new version to your site:

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

This step is extra important, as if you just overwite these files, you will lose all of your custom settings and dictionary items, which is a MASSIVE pain. Once that's done, run the site. You will get the installer, and step through it to upgrade the site. Test your site thoroughly, and repeat for each version!

In addition to the gotchas that are mentioned in the version specific upgrades documentation, I ran into a few additional gotachas which I'll list here for anyone else attempting the same thing:

• if you step through 4.7, in addition to the DLLs that the version notes say to remove, delete the formHandlers DLL and the VistaDB DLLs. Otherwise all of your XSLT macros will break!
• At 4.8, if you are upgrading from v4 (I'm not sure if this will be an issue if upgrading from later versions), you may find that your images embedded in the Richtext editor don't work any more. This is because there is a ~ in all of the paths. If this happens, run the script here and republish your site content.
• Also at 4.8, if you have a Richtext Editor with the context menu disabled, it may stop rendering in the back office. Switch the context menu back on to fix this, and then turn it off again once you've finished upgrading your site.
• 4.8 also breaks uComponents, you'll need to either update uComponets, or use the assembly binding workaround found here.
• At 4.9, it's highly likely that Contour will stop working. Upgrade Contour and you should be good. This was caused by some updates to JQuery in the CMS breaking some dependencies in the CMS.
• 6.0.5 you may find that you need to restart the app pool and clear the Examine indexes, otherwise you'll get null reference errors on the front end and back office. Restarting the app pool fixes these.

Also be sure to test all of your 3rd part DataTypes and extensions. I was pretty lucky, all of mine worked, bar one, which use log4net, which broke when I hit 4.11.10 (when log4net started shipping with umbraco). I fixed it by updaing the package, but I could also have used assembly binding like the uComponents fix.

That's pretty much it! It's a bit daunting if you're not overly technical, but as long as you're patient and careful, performing the upgrade didn't seem to be too painful. I hope this helps anyone else who attempts such a big jump!