Migrate content to Umbraco 15

This article will help you migrate content to Umbraco 15, and outline options to skip this content migration

Umbraco 15 changes the internal data format of all Block Editors.

If you maintain a large Umbraco site with extensive Block Editor usage, the upgrade to Umbraco 15+ might require a long-running content migration. For the duration of the migration, your site will be unresponsive and unable to serve requests.

You can track the progress of the migration in the logs.

It is advised to clean up old content versions before upgrading. This will make the migration run faster.

Parallelizing the content migration

It is possible to parallelize the content migration. This will speed up the migration for large sites.

For certain content structures, parallel content migration will fail. Therefore, parallel content migration is strictly opt-in.

If parallel content migration fails, the database state will be rolled back to the last known good state. You can then disable parallel content migration, and try the migration again.

To enable parallel content migration, add an IComposer implementation to configure the ConvertBlockEditorPropertiesOptions before initiating the upgrade process:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_15_0_0;

namespace UmbracoDocs.Samples;

public class DisableBlockEditorMigrationComposer : IComposer
{
    [Obsolete]
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ConvertBlockEditorPropertiesOptions>(options =>
        {
            // setting this to true will parallelize the migration of all Block Editors
            options.ParallelizeMigration = true;
        });
}

Opting out of the content migration

It is strongly recommended to let the migration run as part of the upgrade. However, if you are upgrading to Umbraco versions 15, 16, or 17, you can opt out of the migration. Your site will continue to work, albeit with a certain degree of performance degradation.

Blocks in Rich Text Editors might not work as expected if you opt out of the content migration.

You can opt out of migrating each Block Editor type individually. To opt-out, add an IComposer implementation to configure the ConvertBlockEditorPropertiesOptions before initiating the upgrade process:

DisableBlockEditorMigrationComposer.cs

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_15_0_0;

namespace UmbracoDocs.Samples;

public class DisableBlockEditorMigrationComposer : IComposer
{
    [Obsolete]
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ConvertBlockEditorPropertiesOptions>(options =>
        {
            // setting this to true will skip the migration of all Block List properties
            options.SkipBlockListEditors = false;

            // setting this to true will skip the migration of all Block Grid properties
            options.SkipBlockGridEditors = false;

            // setting this to true will skip the migration of all Rich Text Editor properties
            options.SkipRichTextEditors = false;
        });
}

Subsequently, you are responsible for performing the content migration yourself. This must be done before upgrading past Umbraco 17.

Custom code is required to perform the content migration. You can find inspiration in the core migrations:

• ConvertBlockListEditorProperties for Block List properties.

• ConvertBlockGridEditorProperties for Block Grid properties.

• ConvertRichTextEditorProperties for Rich Text Editor properties.

This custom code should not run while editors are working in the Umbraco backoffice.

The site may require a restart once the content migration is complete.