This article will provide steps on how to migrate a Cloud project from Umbraco 8 to Umbraco 10.
It is currently not possible to upgrade directly from Umbraco 8 to the latest version.
The recommended approach for upgrading from version 8 to the latest version is to use this guide to upgrade from Umbraco 8 to Umbraco 10 . Umbraco 10 contains the database migrations that must be upgraded from Umbraco 8. You can then use the Major Upgrades steps to upgrade from Umbraco 10 to the latest version.
Since the underlying framework going from Umbraco 8 to the latest version has changed, there is no direct upgrade path. That said, it is possible to re-use the database from your Umbraco 8 project on your new project in order to maintain the content.
It is not possible to migrate the custom code as the underlying web framework has been updated from ASP.NET to ASP.NET Core. All templates and custom code will need to be reimplemented.
You also need to make sure that the packages that you are using are available on the latest version.
A Umbraco 8 Cloud project running the latest version of Umbraco 8.
A clean Cloud project running the latest version of Umbraco with at least 2 environments.
A backup of your Umbraco 8 project database.
We strongly recommend having at least 2 environments on the new Umbraco project.
If your Umbraco 8 site is using Umbraco Forms, make sure to configure it to store data in the database, before beginning this tutorial Follow the guide for migrating Umbraco Forms data to the database.
Should something fail during the migration, the Development environment can be removed and re-added to start over on a clean slate.
If you use Umbraco Forms, make sure to have StoreUmbracoFormsInDbsetto True before step 1.
Create a backup of the database from your Umbraco 8 project using the database backup guide.
Alternatively, you can clone the environment down and take a backup of the local Database after restoring. Make sure to restore both content and media from your Cloud environment after cloning it down.
Import the database backup into SQL Server Management Studio.
Clone down the Development environment from the new Cloud project.
Test the project and make sure to log in to the backoffice.
As you are cloning down a brand new Cloud project there is nothing the restore. Select the "Skip restore and open Umbraco" link when starting up the project locally to go directly to the backoffice.
Update the connection string in the new Cloud projects appsettings.json file so that it connects to the Umbraco 8 database:
You can add the 'umbracoDbDSN_ProviderName' attribute to set the .NET Framework data provider name for the DataSource control's connection. For more information on the data providers included in the .Net Framework, see the Microsoft Documentation.
Enable Unattended Upgrades to authorize the database upgrade.
Run the new Cloud project locally and login to authorize the upgrade.
Select "Continue" when the upgrade wizard appears.
After it has finished upgrading, stop the site and disable the unattended upgrade.
Run the site and log in using Umbraco ID to verify if your project has been upgraded to the new version.
This is only content migration and the database will be migrated.
You need to manually upgrade the view files and custom code implementation. For more information, see Step 3 of this guide.
The following files/folders need to be copied from the Umbraco 8 folder into the new Cloud project folder:
~/Views - Do not overwrite the default Macro and Partial View Macro files unless changes have been made to these.
Any files/folders related to Stylesheets and JavaScript.
~/Media folder from v8 needs to be copied over into the wwwroot - media folder:
Connect to Azure Storage Explorer from the v8 project
Download the media folder from Azure Storage Explorer
Add the downloaded media folder from v8 to the Azure Storage Explorer of the new project.
Migrate custom configuration from the Umbraco 8 configuration files (.config) into the appsettings.json file on the new Cloud project.
As of Umbraco version 9, the configuration no longer lives in the Web.Config file and has been replaced by the appsettings.json file.
Migrate Umbraco Forms data to the database, if relevant.
As of Umbraco Forms version 9, it is only possible to store Forms data in the database. If Umbraco Forms was used on the Umbraco 8 project, the files need to be migrated to the database.
Run the new Cloud project locally.
It will give you an error screen on the frontend as none of the Template files have been updated. Follow Step 3 to resolve the errors.
Go to the backoffice of the project.
Navigate to the Settings section and open the Deploy dashboard.
Click on Export Schema to Data Files in the Deploy Operations section in order to generate the UDA files.
Once the operation is completed, the status will change to Last deployment operation completed.
Check ~\umbraco\Deploy\Revision folder to ensure all the UDA files have been generated.
Return to the Deploy dashboard.
Click on Update Umbraco Schema from Data Files in the Deploy Operations section to make sure everything checks out with the UDA files that were generated.
The latest version of Umbraco is different from Umbraco 8 in many ways. With all the files and data migrated, it is now time to rewrite and re-implement all custom code and templates.
One of the changes is how published content is rendered through Template files. Due to this, it will be necessary to update all the Template files (.cshtml) to reflect these changes.
Read more about these changes in the IPublishedContent section of the Umbraco CMS documentation.
Template files need to inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.HomePage> instead of Umbraco.Web.Mvc.UmbracoViewPage<ContentModels.HomePage>
Template files need to use ContentModels = Umbraco.Cms.Web.Common.PublishedModels instead of ContentModels = Umbraco.Web.PublishedModels
For more information on the correct namespaces or custom code, you can find the references in the API Documentation.
Depending on the extent of the project and the amount of custom code and implementations, this step is going to require a lot of work.
Once the new Cloud project runs without errors on the local setup, the next step is to deploy and test on the Cloud Development environment.
Push the migration and changes to the Umbraco Cloud Development environment.
The deployment might take a bit longer than normal as a lot of changes have been made.
Go to the backoffice of the Development environment once everything has been pushed.
Go to Settings and open the Deploy Dashboard.
Click on Export Schema to Data Files in the Deploy Operations section.
The deployment will result in either of the two:
Last deployment operation failed - something failed during the check.
Select Clear Signatures from the Deploy Operations section.
Select Update Umbraco Schema from the Deploy Operations section to clear up the error.
Last deployment operation completed
Everything checks out: The Development environment has been upgraded.
Transfer Content and Media from the local clone to the Development environment.
To transfer members make sure that the following Deploy settings are configured in the appsettings.json: AllowMembersDeploymentOperations and TransferMemberGroupsAsContent.
Test everything in the Development environment.
Deploy to the Live environment.
Test everything in the Development environment until it runs without any errors.
Setup rewrites on the new Cloud project if relevant.
Assign hostnames to the project if relevant.
Hostnames are unique and can only be added to one Cloud project at a time.
This article will provide detailed steps on how to migrate a Umbraco 7 Cloud project to Umbraco 8.
Taking your Umbraco CMS project from Umbraco 7 to 8 is called a migration as it requires that the data is migrated in the process. This article covers each step involved in this process.
Read the general article about Content migration to learn more about limitations and other things related to migrating your Umbraco site from 7 to 8.
You can find the full playlist here: Migrate an Umbraco Cloud project from 7 to 8
A Umbraco 7 Cloud project running the latest version of Umbraco 7.
Make sure Umbraco Forms data is not handled as content.
See Umbraco Forms on Cloud for more details on how to check the setting.
A clean Cloud project running the latest version of Umbraco 8 with at least 2 environments.
We strongly recommend having at least 2 environments on the Umbraco 8 project.
Should something fail during the migration, the Development environment can always be removed and re-added in order to start over on a clean slate.
Clone down the Umbraco 7 Cloud project.
Run the project locally and restore Content and Media.
Clone down the Development environment from the Umbraco 8 Cloud project.
We recommend setting up the Umbraco 8 Cloud portal locally in Visual Studio.
This can be done after cloning down the Cloud environment or by using the UaaS cloning tool.
To use the cloning tool, place it and run it in the local directory you want to clone the Cloud project into.
Install the ProWorks Umbraco 8 Migrations community package on the cloned Umbraco 8 site.
Copy ~/App_Data/Umbraco.sdf or ~/App_Data/Umbraco.mdf from the cloned Umbraco 7 project.
Paste the file into ~/App_Data on the clone of the Umbraco 8 project.
Open web.config from the Umbraco 8 project.
Locate the Umbraco.Core.ConfigurationStatus key.
Replace the value with the version your Umbraco 7 project is running.
Run the Umbraco 8 project locally
Authorize the migration - Cloud credentials are used for this.
Click Continue to start the migration.
Log in to the backoffice and verify that everything is there once the migration is complete.
If your login does not work, try the following approach:
Copy the UsersMembershipProvider attributes from your Umbraco 7 web.config file to the Umbraco 8 web.config file. Once you've done this, try to login again.
Below is an example of how the attribute can look:
Please be aware that this is only a content migration.
The database will be migrated, but updating view files, custom code, and implementation is a manual process.
See Step 3 of this guide, for more detail on this.
Before moving on to the next 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.
Run the Umbraco 8 project locally
It will give you an error on the frontend as none of the Template files have been updated yet.
Open the command line tool in the ~/data folder on the Umbraco 8 project.
Generate UDA files by running the following command: echo > deploy-export.
Once a deploy-complete marker is added to the ~/data folder, it is done.
Check ~/data/revision to ensure all the UDA files have been generated.
Run echo > deploy in the ~/data folder to make sure everything checks out with the UDA files that were generated.
Running the echo > deploy command will generate a new marker. Move forward with the migration based on the marker:
deploy-failed
Something failed during the check
Run echo > deploy-clearsignatures followed by echo > deploy to clear up the error
deploy-complete
Everything checks out: Move on to the next step
Umbraco 8 is different from Umbraco 7 in many ways. This means that in this step, all custom code, controllers, and models need to be reviewed and rewritten for Umbraco 8.
One of the changes made, is how published content is rendered through Template files. Due to this, it will be necessary to update all Template files (.cshtml) to reflect these changes.
Read more about these changes in the IPublishedContent section of the Documentation.
Template files need to inherit from Umbraco.Web.Mvc.UmbracoViewPage<ContentModels.HomePage> instead of Umbraco.Web.Mvc.UmbracoTemplatePage<ContentModels.HomePage>.
Template files need to use ContentModels = Umbraco.Web.PublishedModels instead of ContentModels = Umbraco.Web.PublishedContentModels.
@Model.Value("propertyAlias") replaces @Umbraco.Field("propertyAlias").
@Model.PropertyAlias replaces @Model.Content.PropertyAlias.
@Model.Value<IPublishedContent>("propertyAlias") replaces Model.Content.GetPropertyValue<IPublishedContent>("propertyAlias").
Depending on the size of the project and the amount of custom code and implementations, this step is going to require a lot of work.
Once the Umbraco 8 project runs without errors on the local setup, the next step is to deploy and test on the Cloud Development environment.
Push the migration and changes to the Umbraco Cloud Development environment
The deployment might take a bit longer than normal.
To track the process, keep an eye on the deploy markers in site/wwwroot/data using KUDU.
Progress through the steps based on the deployment result:
deploy-failed: Run echo > deploy-clearsignatures followed by echo > deploy to clear up the error.
deploy-complete: The Development environment has been upgraded.
Transfer Content and Media from the local clone to the Development environment.
Test everything on the Development environment.
Deploy to the Live environment.
Once the migration is complete, and the Live environment is running without errors, the site is almost ready for launch.
Setup rewrites on the Umbraco 8 site.
Assign hostnames to the project.
Hostnames are unique, and can only be added to one Cloud project at a time.
This article provides an overview of any version-specific steps that might be necessary when upgrading your Umbraco Cloud project to a new version.
As there might also be version-specific notes for the specific products involved in the upgrade it is recommend giving those a look as well.