diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index e3af8286c61..b49513edbc8 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -21,6 +21,7 @@ * [Upgrade your project](fundamentals/setup/upgrading/README.md) * [Version Specific Upgrades](fundamentals/setup/upgrading/version-specific/README.md) * [Upgrade from Umbraco 8 to the latest version](fundamentals/setup/upgrading/version-specific/upgrade-from-8-to-latest.md) + * [Migrate content to Umbraco 15](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md) * [Migrate content to Umbraco 8](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-8.md) * [Minor upgrades for Umbraco 8](fundamentals/setup/upgrading/version-specific/minor-upgrades-for-umbraco-8.md) * [Upgrade to Umbraco 7](fundamentals/setup/upgrading/version-specific/upgrade-to-umbraco-7.md) diff --git a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md index 1b00841cce7..e66effe6766 100644 --- a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md +++ b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md @@ -1069,6 +1069,14 @@ Macros and partial views macros have been removed in Umbraco 14. We recommend us For more information on what has changed in Umbraco 14 read the [Breaking changes in Umbraco 14](./#umbraco-14). +**Block Editor data format has changes** + +In Umbraco 15, the internal data format for [Block Editors](../../../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md) has changed. This causes a content migration to run when upgrading. + +This content migration can take a while to complete on a large site, causing it to be unresponsive for the duration. To speed up the migration, it is advised to [clean up old content versions](../../../../fundamentals/data/content-version-cleanup.md) before upgrading. + +While we don't recommend this, it might be possible for you to skip the content migration. More details can be found in the [Migrate content to Umbraco 15](migrate-content-to-umbraco-15.md) article. +
diff --git a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md new file mode 100644 index 00000000000..2b03fbc5e2b --- /dev/null +++ b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md @@ -0,0 +1,66 @@ +--- +description: >- + This article will help you migrate content to Umbraco 15, and outline options to skip this content migration +--- + +# Migrate content to Umbraco 15 + +Umbraco 15 changes the internal data format of all [Block Editors](../../../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md). + +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](../../../../fundamentals/data/content-version-cleanup.md) before upgrading. This will make the migration run faster. + +## 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. + +{% hint style="warning" %} +Blocks in Rich Text Editors might not work as expected if you opt out of the content migration. +{% endhint %} + +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: + +{% code title="DisableBlockEditorMigrationComposer.cs" %} + +```csharp +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(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; + }); +} +``` + +{% endcode %} + +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`](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Infrastructure/Migrations/Upgrade/V_15_0_0/ConvertBlockListEditorProperties.cs) for Block List properties. +- [`ConvertBlockGridEditorProperties`](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Infrastructure/Migrations/Upgrade/V_15_0_0/ConvertBlockGridEditorProperties.cs) for Block Grid properties. +- [`ConvertRichTextEditorProperties`](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Infrastructure/Migrations/Upgrade/V_15_0_0/ConvertRichTextEditorProperties.cs) for Rich Text Editor properties. + +{% hint style="warning" %} +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. +{% endhint %}