Upgrading Umbraco 4.x to 7.x

I have been working on an exciting project that had to get past a rather daunting hurdle before it could start properly – we needed to upgrade the Umbraco database multiple versions whilst retaining all user content (some 15,000 nodes).

This was, obviously, a somewhat scary prospect. Our project scope document contained many fallback options should the somewhat-direct upgrade path should fail. The TLDR; version – no fallback options were required and we successfully upgraded Umbraco 4.11.10 to 7.3.8. Let me detail how we achieved it.

Important note – we had NO requirement to keep the existing front end of the website. Our project involved upgrading the Umbraco database to a 7.x version. The fun part of the project was the total rebuild of all website templates using the 7.x MVC technologies, rather than keeping the legacy 4.x Webforms and XSLT macros and templates.

However, it IS important to migrate the website portion along the way. How else can you truly test at each step if there the database has successfully updated without an Umbraco back-office to prove it?

Our upgrade path was 4.11.10 > 6.0.0 > 6.2.6 > 7.3.8. As you may notice we skipped 7.0.0 – I will explain why as I go.

The upgrade was performed with a local IIS on Windows 8 with a local SQL 2014 database. I used Visual Studio 2015 for all the changes and merging. If you are doing this under TFS source control, check out EVERYTHING before you start.

After each successful upgrade – and this is important – made a backup of the code and database, then checked in both as an isolated version. This came in handy later for referring to how the site was at a certain version.

The Umbraco back-office was thoroughly tested after each upgrade (the website front end, less so).

Reference guides

http://www.blix.co/blog/2014/6/5/follow-the-path-upgrading-umbraco-from-v4-to-v7.aspx

https://our.umbraco.org/documentation/Getting-Started/Setup/Upgrading/upgrading-to-v7/

Umbraco version archive

http://code.leekelleher.com/umbraco/archive/

4.11.10 > 6.0.0

Download 6.0.0 from the archive.

Copy and overwrite:

• /install
• /bin
• /Umbraco
• /Umbraco_Client

Copy and overwrite, then merge in changes:

• /Config
• /Global.asax
• /web.config
• /Views/web.config

On first load, the site threw this error: Could not load type 'Umbraco.Web.IApplicationEventHandler'

I deleted the bin contents and brought across only the 6.0.0 native files and progressively fixed each error that came up after a refresh, until I got to custom libraries created by the previous developers of the site we were upgrading. I excluded all references to them in the web.config as they did not appear to be required for

The database upgrade via /Install worked 4.11 > 6.0 after the above was done.

Path fix up

If you are upgrading from 4.10 or 4.11, you need to apply the Path Fixup patch AFTER the migration to 6.0. This fixed media paths that are broken by the upgrade tool.

It is an Umbraco plugin that you need to install into your 6.0.0 running version. Download it here.

6.0.0 > 6.2.6

Download 6.2.6 from the archive.

Copy and overwrite:

• /install
• /bin
• /Umbraco
• /Umbraco_Client

Copy and overwrite, then merge in changes:

• /Config
• /Global.asax
• /web.config
• /Views/web.config

This time I was more forgiving with the /Config changes as I really was not trying to preserve the front-end site anymore, nor things like the 301 redirector interface. ExamineIndex is back to defaults for example – again not caring, as the search will be rewritten

At this point I re-included the uBlogsy and uTube plugins from the 4.11 install to bring those datatypes back. In hindsight this too was not required – the plugins were not supported in 7.x anyway.

Amusingly, most of the website was still functioning at this point.

6.2.6 > 7.3.8

This is where things got a little hairy (as expected – 7.x was a complete rewrite).

Initially I upgraded 6.2.6 (the last version of 6.x) to 7.0.0, as suggested by the upgrade guide above. This proved disastrous, in my instance. I had issues getting a particular nested datatype and its children to load content in the back office once the 6.2.6 > 7.0.0 was complete. I found no solution so installed a fresh 7.3.8 project and pointed it to a copy of the 6.2.6 database.

I was warned about the following data types being disabled (obviously these are custom to the project, but are instances of types you may be familiar with):

1. Property Editor with ID '31235fd3-d366-49c1-ab19-9d3ec5d9bec0' (assigned to Data Type 'uTube Video Uploader') does not have a valid GUID -> Alias map. It will be replaced with a Readonly/Label property editor.
2. Property Editor with ID '2cb7b4b8-a92d-4280-906b-8ff0dda54960' (assigned to Data Type 'uTube Single Video Picker') does not have a valid GUID -> Alias map. It will be replaced with a Readonly/Label property editor.
3. Property Editor with ID '676b15b8-93cf-48c4-87b7-889c329b3089' (assigned to Data Type '301 URL Tracker') does not have a valid GUID -> Alias map. It will be replaced with a Readonly/Label property editor.
4. Property Editor with ID '60a73e32-c48d-11de-b452-fc9f55d89593' (assigned to Data Type 'Form picker') does not have a valid GUID -> Alias map. It will be replaced with a Readonly/Label property editor.

I set these to Label / Umbraco.NoEdit datatype to preserve the content entered against these properties.

The database upgraded with two errors:

"Umbraco.Web.Install.InstallException: The database failed to upgrade. ERROR: The database configuration failed with the following message: '', hexadecimal value 0x08, is an invalid character."

The character won't render above but it was a black rectangle with white circle like a domino. Refreshing the installer brought this error:

"Umbraco.Web.Install.InstallException: The database failed to upgrade. ERROR: The database configuration failed with the following message:

Invalid column name 'controlId'.""

At this point Google suggested just setting the umbracoConfigurationStatus to 7.3.8 and be done with it.

This has resulted in a functioning back office in a new project with no legacy templates, and a couple of rarely used plugins awaiting upgrade (i.e. great success!)

Note – you may, and probably will, encounter extra datatypes that cannot be upgraded. The way plugins are written was completely changed in 7.x and may 4-6.x tools were never brought up to speed. The 7.x installer should inform you of these as it tries the upgrade.

Post-upgrade clean up

Affter the upgrade, I noticed that prevalues for ALL dropdown lists had vanished. Somewhere during the Umbraco upgrade cycle these were deleted. THIS is why keeping backups of the databases as you go is massively important.

Using RedGate Data Compare I was able to generate a SQL comparison script that inserted the data from cmsDataTypePreValues from the untouched 4.11.10 database to the 7.3.8 database – thankfully the schema had not changed in this table. This restored the prevalues for all dropdown lists successfully.

Legacy datatypes needed to be replaced – like the aforementioned uTube and uBlogsy, as well as Umbraco Contour (now Umbraco Forms). All were replaced during the post-upgrade site rebuild process with new tools or custom code.

Why I skipped 7.0.0

Officially you are meant to take the highest version of the current major Umbraco to the first version of the next major Umbraco i.e. 6.2.6 to 7.0.0. Feeling overly cautious, I went this route first (despite the Blixology article mentioned in the references section going straight to 7.2.6 from a 6.x version).

This was a bad idea and I should have stayed the course, going from 6.2.6 to 7.3.8 directly.

There were many foreign key errors reported by the installer. These were mostly solved by the scripts mentioned in the Blixology article for 7.1.2 (surprisingly not needed for my 7.3.8 upgrade – I guess the installer was improved in the two years since that article was written).

The installer still would not complete, referencing errors in FK_cmsTagRelationship_cmsContent. This was solved using this guide.

The database upgraded fine now. Had I been doing this blind without testing the results in Umbraco back-office I would have moved on to the final upgrade. Thankfully I did test, because this is where I encountered the bug with three-level nested doctypes refusing to load in content editors. The error referred to duplicated tabs or properties, but I found no such evidence that this was occurring. In the end I could not resolve it, so tried the upgrade again from 6.2.6 to 7.3.8. As mentioned above. The installer/upgrade software must have improved significantly as there were no problems here.