Migrate content to Umbraco 8
This guide will show you how to migrate the content from your Umbraco 7 site to a site running Umbraco 8.
Umbraco 8 contains a lot of breaking changes and a lot of code has been cleaned up compared to Umbraco 7. Due to this, it will not be possible to do a direct upgrade from Umbraco 7 to Umbraco 8. You need to migrate your content from your Umbraco 7 site into your Umbraco 8 site and then recreate the rest in the new version.
A content migration tool has been implemented in Umbraco 8.1.0, to help you with the transition.
In this guide you can read more about the tool, its limitations, and how to use it in practice.
Migrating Umbraco Cloud sites
Follow the steps outlined in the Umbraco Cloud documentation to upgrade your Umbraco 7 site on Cloud.
What are the limitations?
In the following section, you can learn more about the limitations of migrating content from Umbraco 7 to Umbraco 8.
Versions supported
The content migration tool is a database migration, which is made for the database schema of Umbraco 7.14+. This means that in order to do the migration you need to ensure your Umbraco 7 site is running at least Umbraco 7.14.
Database types supported
Umbraco 8 does not support MySQL databases. This means that the migration will not work when moving from an Umbraco 7 site using MySQL to Umbraco 8 on SQL Server
The database types that are supported are SQL Server and SQL CE.
Known issues
Feedback from user testing has shown that some databases are harder to migrate than others.
We are collecting a list of these known issues on our GitHub Issue Tracker. There is a community package: Pre-migration health checks that you can install on your Umbraco 7 site before migration. This will help identify and resolve some of these common issues before triggering the migration steps detailed below.
A migration was introduced in Umbraco 8.6 which can break the migration process. See Issue #7914 for more details.
There are two ways to work around this issue:
Migrate to version 8.5 as a first step and then post-migration, carry out a normal Umbraco upgrade to the latest version of Umbraco 8, or
Install the following community Nuget Package: ProWorks Umbraco 8 Migrations into your Umbraco 8 project before running the migration (no configuration required). This package was created by Umbraco Gold Partner ProWorks and patches the migration process so you can migrate directly from the latest Umbraco 7 to Umbraco 8.6+ without encountering the above issue. Learn more about the package and the migration process on Prowork's blog.
Third party property editors
The migration will transform the data stored in third party editors as well. However, it will be stored as it was in Umbraco 7. If the structure has changed or the property editor doesn't exist, you will still be able to find the data in the database. It will, however, not be available in the backoffice.
What will happen
When the migrations are running, Umbraco will go through your entire Umbraco 7 database and update it to the format required for Umbraco 8. The schema will be remodeled and transformed into the correct format and your existing compatible data will be transformed to fit with Umbraco 8.
These migrations will be running directly on your database. They are transforming schema and data - not transferring. Therefore always ensure that you have a backup before attempting to do this. In case something goes wrong, you will be able to rollback and try again.
It is highly recommended to clean up your site before running this as it will be quicker.
Empty Content recycle bin
Empty Media recycle bin
Clean up the database version history (can be done with a script or a package like Unversion)
How it works
In the following guide we will migrate the content of an Umbraco 7.13.1 site to Umbraco 8.1.0.
Step 1: Upgrading to 7.14+
Before the content migration can start the site has to run Umbraco 7.14+. Make sure to always take a backup of the database before doing an upgrade, and then check the version specific upgrade instructions.
The site in this example is an Umbraco 7.13.1 site, and we will use Nuget to update it.
Following the general upgrade instructions we will now upgrade via Nuget until we get to this point:
When upgrading an old website, check if you are using obsolete properties in your Data Types. These should be changed to their updated counterparts. The migration will fail if you are still using obsolete properties.
The updated properties are:
Content Picker
Media Picker
Member Picker
Multinode Treepicker
Folder Browser
Related Links
You can see if your site is using the obsolete properties from the (Obsolete)
prefix in their name.
Install the Pre-migration health checks plugin, and run it health check from the Developer section of the backoffice. This is done to identify and resolve some common database schema issues before migration.
Once it is upgraded and you have verified everything is working, move on to the next step.
Step 2: Migrating content to Umbraco 8
The first thing to do is to spin up a fresh new Umbraco 8.1+ site. Make sure everything works and that no content is there.
If you have customized the UsersMembershipProvider
on your Umbraco 7 site you need to copy that over to the 8.1 web.config
as well. Additionally you need to update the type
attribute to be type="Umbraco.Web.Security.Providers.UsersMembershipProvider, Umbraco.Web"
.
This also includes the attribute useLegacyEncoding
value. Make sure that this setting is copied into your new Umbraco 8 site, as it is needed in order to log in.
Take a backup of your database from the Umbraco 7.14 site. Take the information for the backup database and add that to the connectionstring for the Umbraco 8.1 site. If you are running SQL CE, you will have to copy the database over to the new site as well.
Once the connectionstring is set, the final step is to change the Umbraco version number in the web.config
on the Umbraco 8.1 site. Chang it to 7.14.0
. This will indicate that there is an upgrade pending and it needs to run the migration.
The version will be set to 8.1.0, and you need to change it to the version you are currently migrating from.
When you start the site it will ask you to login and then show you this screen:
From here, the automatic migration will take over, and after a little bit you can log in and see your content:
Please be aware that this is a content migration. If you go to the frontend after following these steps, it will throw errors.
At this point you will have the content but nothing else.
Step 3: Files migration
Before moving on to this step, make sure that the Umbraco 8 project is no longer running.
The following files/folders need to be copied into the Umbraco 8 project:
~/Views
- do not overwrite the default Macro and Partial View Macro files, unless changes have been made to these.~/Media
Any files/folders related to Stylesheets and JavaScripts.
Any custom files/folders the Umbraco 7 project uses, that aren't in the
~/Config
or~/bin
.~/App_Data/UmbracoForms
- in the case Umbraco Forms was used on the Umbraco 7 site.
Merge the configuration files carefully to ensure any custom settings are migrated while none of the default configurations for Umbraco 8 is overwritten.
You'll have to revisit all templates and custom implementations to get the site up and running, as all markup is still Umbraco 7-specific.
Are you planning on continuing the migration to the latest version on Umbraco CMS?
Then you can skip the step to revisit the template files and custom implementation. We highly recommend waiting with this step until you've reached the latest version.
If you're stopping at Umbraco 8, you can learn more about rendering content on the Legacy Docs site.
Step 4: Post-migration checks
As you are updating your template files and custom implementation, you should also verify your configuration files and settings.
Umbraco 8 contains a few changes regarding the Sections in the Umbraco Backoffice. Because of this, you should also check your User Groups and make sure they have access to the appropriate sections.
Learn more about the Section in the Sections article
Last updated