Upgrading Umbraco 7 to Umbraco 13

This is my journey about updating an Umbraco 7 website to the latest version of Umbraco - which is Umbraco 13 as of today.

The first thing you want to do is migrate the content from Umbraco 7 to Umbraco 8. Unfortunately, you cannot update right from Umbraco 7 to the latest version of Umbraco 13. Due to database changes and Umbraco schema changes this just isn't a path. In order to get to the Umbraco 13 you have to do incremental updates and migrations. First off is a content migration from database to database and then manually update whatever content didn't come over. Once the content is in a good place, you need to update your back end code and views to be compatible with the newest version of Umbraco. Namespaces and classes have been updated, not to mention you are working with a whole new version of .Net now.

In this post I will walk through the steps I took to migrate/update my Umbraco 7 instance up to Umbraco 13 while documenting errors, pitfalls, what worked and what didn't work along the way.

Let's begin.

uSync of upgrade

Instead of trying to do an in-place upgrade of the Umbraco database and code, I decided to use uSync to migrate the content. This means I create a fresh Umbraco install of the version that I want to upgrade to and then run a sync process that imports the data into the new database format. This sounds pretty straight forward but there are a couple hoops you have to jump through in order to get this working properly. Luckily for me the fine folks at Jumoo have written a good step by step guide for this process, you can also follow the guide that is detailed here in the Jumoo Github repository.

To start off I install uSync into my source Umbraco 7.5.10 site. This is going to allow me to do an export of all my data which will eventually be imported into the new Umbraco instance.

• Install uSync and supporting packages in your Umbraco 7 project. I used NuGet to install these versions. Make sure you install the versions that are compatible with your Umbraco version. I installed uSync, uSync.BackOffice and uSync.ContentEdition

• Download uSync.Migrations.Packer v7 package from GitHub and install it in your Umbraco 7.5 instance. This is a uSync package that will help prepare your 7.5 content to be exported in a format that can be imported into the latest version of Umbraco.
• After you download the package, navigate to the Umbraco back office --> Developer --> Packages --> Install local and add the package zip file.
• After that package is installed, navigate back to the Developer landing page and select the uSync BackOffice tab. The URL for this tab is /umbraco/#/developer - I mention this because I could not find that tab after I installed the package. The older version of Umbraco was new to me as I'm familiar with the modern version of Umbraco, so it took me a little while to figure out how to get to this tab.
• Click the Migrations tab and make pack button.

• Now uSync will do it's thing and eventually create a .zip folder containing your Umbraco 7 content. Download and save the .zip file to a location you can get to from your new Umbraco installation.

Install a fresh Umbraco 12 site

Now that the data is exported from Umbraco 7, we need to create your fresh new Umbraco 12 site.

This post is about migrating to Umbraco 13, however the code below uses a package called uSync Migrations and uSync Migrations does not support Umbraco 13 at the time of this post. So, we will need to migrate to Umbraco 12 and then upgrade to Umbraco 13 after the migration is complete.

• Start by installing the Umbraco 12 templates for dotnet. Installing these templates will overwrite any Umbraco templates you already have created on your machine. So if you have 13 templates installed, you will need to reinstall them after this migration is complete.
• Then run the following command from a command prompt:

dotnet new install Umbraco.Templates::12.3.7

• You now should have the Umbraco 12 templates installed on your machine. As you can see my Umbraco 13 templates were uninstalled before the version 12 templates were installed.

• Next create a new Umbraco 12 project:

dotnet new umbraco -n MyUmbraco
dotnet build
dotnet run

• You will now be able to configure your new Umbraco 12 project and website. This is going to be your new Umbraco 13 project solution and website. So go through the steps to configure the database and Umbraco website to match what you want the final Umbraco 13 site to be. Eventually this site will get upgraded to Umbraco 13.
• Once the site is configured, install these uSync packages for Umbraco 12.

dotnet add package uSync --version 12.2.3
dotnet add package uSync.Migrations --version 4.0.0-phase.5.1

Migrate

After the new Umbraco 12 website is configured with uSync and uSync Migrations you are ready to do the migration. Again the Jumoo team does a fantastic job of documenting the necessary steps for a migration, so instead of copying what they've arleady written follow the steps provided by the Jumoo team on the uSyncMigrations repo page.

Once the migrations are all completed, you should have a content tree populated with the content from the Umbraco 7 site as well as all the other content from your Umbraco 7 site in your Umbraco 12 site.

Upgrade to Umbraco 13

The next step is to upgrade from Umbraco 12 to Umbraco 13 which should be pretty easy and straight forward. To do the upgrade to Umbraco 13 just follow these instructions to upgrade to Umbraco 13.

Update code and view files

That's all there is to getting the content from Umbraco 7 into your new Umbraco 13 project. The next step is to update all the custom code behind and views from your Umbraco 7 project.

There are a lot of steps to go through in order to complete this upgrade. I started by copying over a simple content template and then configuring the Document Type to that new template.