Use Converge to Upgrade to Umbraco 8

Instead of using the Umbraco migration process, I create an empty installation of Umbraco V8 and migrate the V7 site into it using Converge. For the example site I will use the Starter Kit that can be installed with Umbraco, it is relatively simple and hopefully familiar to Umbraco developers.

Creating the Umbraco Source Site

For the example "source" site I created a .NET Framework project and installed version 7.15.6 of Umbraco using NuGet.

During the Umbraco "Build" process I selected to include the Starter Kit, giving the following content, along with associated media, document types, data types, etc. Installing the Starter Kit also installs some code into the project.

I then installed the Converge package onto the V7 site. At the time of writing this had to be done in the Developer section of the Umbraco back office, in the future I intend to have a NuGet package. It will also be possible to just install the Converge API package as we are only going to be reading from this site.

Creating the Umbraco Destination Site

I then created the new site with version 8.8.0 of Umbraco. I did not install the starter kit as this site must be empty, the V7 content will be copied into it using Converge.

I then installed Converge using NuGet. At this stage (while the site is clean and empty) I took a backup of the database, so I could return to this point if need be after experimenting with the migration.

Initial Compare

I could now run the Umbraco 8 site and access the Converge section in the back office. I selected "Merge from Remote" and entered the URL and login details of the Umbraco 7 "source" site from which we will take the content.

Converge connects to the "remote" (or "source") site and collects all the content information from it, it then compares that site with this "local" site and displays the differences. As all the content only exists on the remote Umbraco 7 site and there is no equivalent on the local Umbraco 8 site, it is considered "RemoteNotLocal".

Scrolling down the comparison you will see sections for:

• Content
• Content Templates
• Media
• Document Types
• Media Types
• Data Types
• Templates
• Dictionary Items
• Macros

Initial Merge

As I could always restore back to this state (from the database backup), I decided to try a merge to see what happened. To do this I just pressed the "Merge" button at the bottom of the page.

The merge took less than a minute and seemed to be mostly successful. But there was an error on the "Contact" page. Hovering over the "ErrorMerging" status provides further information.

You can see that there is a problem with the document type. Scrolling down further revealed that there were problems with both the "Contact" and "Home" document types. Both were as a result of an error with the data types.

Scrolling down further, I could see that the "Terratype" property editor was missing, which is used for displaying the map on the Contact page.

I will explain in another blog post how I resolved this issue, as it involves some extra coding, but let us take a look at the parts of the site that were brought across successfully here.

Checking the Merged Content

Using the Umbraco back office I checked the content that had been transferred and it all seemed to be in a good state.

All the media had been successfully transferred.

Code Changes

I decided to take a look at what the site looked like by visiting the home page and, unsurprisingly, I saw my first error.

Converge has created the Home.cshtml page as a view, copying the code directly from the Umbraco 7 version. This is no longer suitable for Umbraco 8. Here I will list the changes that I made to all of the views, but you may also find others are required in your own code to make it work with Umbraco 8.

• Rename "UmbracoTemplatePage" to "UmbracoViewPage".
• Rename "Umbraco.Web.PublishedContentModels" to "Umbraco.Web.PublishedModels".
• "Content" is no longer a field under "Model", e.g. "Model.Content.HeroBackgroundImage" becomes "Model.HeroBackgroundImage".
• Rename "Model.Site()" to "Model.Root()".
• There is no longer any need to use "GetPreValueAsString()" when using the models builder. Just use "Model.[property]".
• Rename "Umbraco.TypedContent()" to "Umbraco.Content()".
• Rename "Model.GetPropertyValue()" to "Model.Value()".
• The model in the macro files has changed. Use "Model.Content.[property]" rather than "Model.[property]".

In this case there were also missing Partial View files, so I copied them across to the new project.

After fixing all of the errors, I saw an unformatted site, which looked like it contained all of the correct information.

Copying across the "scripts" and "css" folders resolved the formatting.

It should be remembered that all of the code changes only need to be made once for a migration project. The Converge compare and merge can be run multiple times, it will pick up differences between the sites and apply the updates required. Thus, while you are building your migration process the content of your live site can be updated and these updates regularly transferred to the newer version of the site.

If you want to find out more about using Converge then please take a look at the user guide.