In this troubleshooting section, you can find help to resolve issues that you might run into when using Umbraco Deploy.

If you are unable to find the issue you are having, then please reach out to our friendly support team at contact@umbraco.com.

Schema mismatches

When transferring or restoring content between two Umbraco Deploy environments, you might run into Schema mismatch errors. For more information on how to resolve schema mismatch issues, see the Schema Mismatches article.

Umbraco Deploy maintains a cached set of signatures that represent each schema and content item. They are used when transferring or restoring content between environments to aid performance.

If having resolved schema mismatches you still have reports of errors, it might be that the signatures are out of date. In other words, Deploy is using a cached representation of an item that no longer matches the actual item stored in Umbraco.

This should not be necessary in normal use, but can occur after upgrades. If you have this situation, you can clear the cached signatures in both the upstream and downstream environments. You do this via the Clear Cached Signatures operation available on the Settings > Deploy dashboard:

Slow responses or timeouts when restoring or transferring

When transferring or restoring content between environments, Deploy needs to ensure that all related items are updated together. It also checks that any schema dependencies an item has also exist in the target environment. When a large amount of content is selected for transfer or restore, this process of determining all the dependent items can take some time.

In some cases, a hard limit imposed by the Cloud hosting platforms such as Azure, used by Umbraco Cloud, can be reached.

If you find the process slow or reporting a platform timeout, there are a few options you can take.

Consider partial restore

If restoring, you can choose to pull down a smaller set of content via the partial restore feature. With this you select an item in the remote environment to restore. You can select to include child items. Any items related to the selected ones, for example via content or media pickers, will also be restored.

Consider import/export

In addition to transferring content via the backoffice, it is possible to move both content and schema between environments via Deploy's import/export feature. With this, a selection of Umbraco data can be exported from one environment to a .zip file. That file can then be imported into another environment.

As this process requires less inter-environment communication, it's possible to transfer much larger amounts of content without running into the hard platform limits.

Read more about the import/export feature here.

Review timeouts

Firstly, you can review and update the timeout settings available with Deploy. Increasing these from the default values may help, but won't necessarily resolve all issues. This is because, as noted, some timeouts are fixed values set by the hosting environment.

Use batch configurations

There are two places where Deploy operations can be batched. This allows breaking up of a single, long process into multiple, smaller ones. By doing this it's possible to complete each smaller operation within the platform imposed timeout.

For transfers to upstream environments

If transferring items from a downstream environment to an upstream one, it's possible to configure a batch size. With this in place, transfers will be batched into separate operations, allowing each single operation to complete before any hosting environment-enforced timeout.

This will take effect only for transfers to upstream environments and when multiple items are selected in the backoffice. An example is the selection of a single media folder containing many files.

For processing of a Deploy "package"

A package is an ordered structure containing all the items selected for a Deploy operation, plus all the determined dependencies and relations. The processing of this package in the target environment can also be batched via a configuration setting.

When set, if the number of items determined for the package exceeds the batch size, the processing will be chunked into batches.

Ensure signatures are pre-cached

For transfer or restore operations, it's worth ensuring Deploy's cached signatures are fully populated in both the upstream and downstream environments. This can be done via the Set Cached Signatures operation available on the Settings > Deploy dashboard:

The process make take a few minutes to complete if you have a lot of content or media in your installation. Information is written to the log indicating the signatures calculated for each entity type.

Now the checks Deploy has to do to figure out the items and dependencies to process will complete much more quickly.

Modify the checksum calculation method for media files

Deploy will do comparisons between the entities in different environments to determine if they match and decide whether to include them in the operation. By default, for media files, a check is made on a portion of the initial bytes of the file.

If a lot of files need to be checked, this can be slow, and a faster option is available that uses the file metadata. The only downside of changing this option is a marginally increased chance of Deploy considering a media file hasn't changed when it has. This would omit it from the deployment.

This option can be set in configuration.

Consider disabling cache refresher notifications

When a Deploy operation completes, cache refresher notifications are fired. These are used to update Umbraco's cache and search index.

In production these should always be enabled, to ensure these additional data stores are kept up to date.

If attempting a one-off, large transfer operation, before a site is live, you could disable these via a configuration setting. That would omit the firing and handling of these notifications and remove their performance overhead. Following which you would need to ensure to rebuild the cache and search index manually via the backoffice Settings dashboards.

Review relation types included in deploy operations

As well as transferring entities between environments Deploy will also include the relations between them. As of 10.1.2 and 11.0.1, two relation types used for usage tracking are omitted by default. These do not need to be transferred as they are recreated by the CMS as part of the save operation on the entity.

If using an earlier version, or to make further adjustments, modify the settings for relation types in configuration.

Path too long exceptions

When restoring between different media systems exceptions can occur due to file paths. They can happen between a local file system and a remote system based on blob storage. What is accepted on one system may be rejected on another as the file path is too long. Normally this will only happen for files with particularly long names.

If you are happy to continue without throwing exceptions in these instances you can modify the configuration. If this is done such files will be skipped, and although the media item will exist there will be no associated file.

Schema files following upgrades

When Umbraco schema items are created, a representation of them is saved to disk as a .uda file in the /data/revision/ folder. The representation is known as an artifact. It will be refreshed on further updates to represent the current state of the schema item.

Following an upgrade, it's possible the contents of the file will no longer match what would be generated by the current version. For example, if a property has been added to an artifact, this will be absent in the file. It would be added if the file was recreated following the upgrade.

This can lead to situations where Deploy continues to process a file it considers changed, even though the item represented is up-to-date. This in turn means slow updates of Umbraco schema, as Deploy is processing more files than it needs to do.

To resolve this situation, following an upgrade, it is good practice to re-save the .uda files in the "left-most" environment. This will usually be the local one, or if not using that, the Development environment. You can do this via the Export Schema To Data Files operation available on the Settings > Deploy dashboard:

The updated files should be committed to source control and deployed to upstream environments.

In this section we have summarised the changes to Umbraco Deploy and Deploy Contrib released in each version. Each version is presented with a link to the Deploy issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release History

This section contains the release notes for Umbraco Deploy 13 including all changes for this version.

13.3.0-rc1 (November 13rd 2024)

• Add option to include all schema in a workspace export

• Add option to export from transfer queue

• Combine migrated grid editor with default Block Grid block configuration (set RowMinSpan and RowMaxSpan to 1 and EditorSize to medium)

• Import on startup

• Added ValidateDependenciesOnImport setting to disable dependency validation on import

• Fixed issue where content was not saved when transferring variant content with a release date

• Support flexible environments on Umbraco Cloud (remove requirement for environment types to be Development, Staging or Live)

13.2.2 (October 3rd 2024)

• Support migrating legacy Grid editor settings (config/styles) using JSON object pre-values

13.2.1 (September 17th 2024)

• Fix tree export of members by member type

• Ensure release date of invariant content is correctly transferred #233

• Parse nested JSON property values from artifact values #234

13.2.0 (August 15th 2024)

• All items from 13.2.0-rc1

• Fixed Could not create Udi node: {Id} and entity type {EntityType} exception when exporting tree nodes without children

• Fixed deploy signatures not getting cleared when members are deleted #230

• Allow members to be deployed when selected as items in a multi-node tree picker #231

• Apply ExcludedEntityTypes configuration to disk operations #232

13.2.0-rc1 (July 19th 2024)

• Add migrators to support legacy Grid layout to Block Grid migration

13.1.1 (July 11th 2024)

• Add [DisableRequestSizeLimit] attribute to UploadForImport endpoint to remove application request size limit (server/infrastructure restrictions may still apply)

• Determine missing routePath based on $routeParams to fix Export, Queue for transfer, and Partial Restore actions on items with children in a list view

• Set trashed state when processing content #223

• Improve exception message when parent cannot be found when getting artifact #216

13.1.0 (March 19th 2024)

• All items from 13.1.0-rc1

• Fixed issue with transfer of date values within Nested Content, Block List, or Block Grid properties #209

• Fixed issue where templates could incorrectly cause schema mismatch errors when running in production mode #187

• Fixed issue where importing invalid variant property data would cause a not supported variation exception #8

• Fixed deserialization issue causing problems with the compare content feature #212

• Add configuration to allow control over suspension and resumption of Examine and document cache events during Deploy operation #211

13.1.0-rc1 (March 5th 2024)

• Add IArtifactTypeResolver to allow custom type resolving when deserializing to IArtifact (used by Deploy Contrib, see PR #60)

• Add base migrators for importing legacy artifacts (used by Deploy Contrib)

• Restored ability to overwrite content properties with empty values

• Improved error UX and messaging to only show technical detail option if available

• Require a valid license when importing

• Only validate ApiKey and ApiSecret when workspaces are configured

• Explicitly register API controller endpoints

13.0.4 (February 20th 2024)

• Removed the no-longer supported "live edit" feature (Deploy on Cloud only).

• Fixed issue where the removal of a master template couldn't be deployed #201

• Ensured configuration for behavior following a "path too long" exception is respected for handling image cropper values #200

• Added configuration setting to allow hiding of version details on the settings dashboard.

• User experience and message improvements on content flow exception #202

• Fixed issue with transfer of empty values to overwrite non-empty ones.

13.0.3 (January 16th 2024)

• Added configurable option to avoid overwriting of dictionary items with empty values #191

  • For more details see the page on Deploy's settings.

• Fixed regression issue with transfer of date values.

13.0.2 (January 9th 2024)

• Fixed issue with transfer of content using language variants #193

13.0.1 (December 21th 2023)

• Fixes the display of the selected schedule date on queue for transfer.

• Fixes parsing property values within Nested Content and Block List that were previously saved by the Contrib value connectors.

• Fixed incorrectly including media files in export when 'Content files' wasn't selected.

• Add maximum file size validation to import file upload.

13.0.0 (December 14th 2023)

• All items from the 13.0.0 RCs and latest 12.2 features.

13.0.0-rc5 (December 12th 2023)

• Align with latest CMS RC.

13.0.0-rc4 (December 11th 2023)

• Add weight -100 to Deploy package migration (ensuring Deploy database tables are available before other package migrations are executed).

• Add fluent API for Deploy webhooks.

13.0.0-rc3 (November 29th 2023)

• Added optional deployment of webhooks as part of schema updates.

• Added Deploy specific webhook events.

13.0.0-rc2 (November 15th 2023)

• Exclude automatic relation type aliases (used for reference tracking) from deployment.

• Fix cyclic dependency between configuring DeploySettings and ConnectionStrings.

13.0.0-rc1 (November 6th 2023)

• Compatibility with Umbraco 13:

  • See full details of breaking changes under the version specific upgrade guide.

  • Update Richtext value connector to handle references in blocks.

Deploy Contrib

13.3.0 (October 3rd 2024)

• Migrate nested/recursive legacy pre-value property values #71

13.2.0 (August 15th 2024)

• All items from 13.2.0-rc1

13.2.0-rc1 (July 19th 2024)

• Skip empty pre-values #63

• Add Matryoshka Group Separator artifact migrator #67

• Add migrators to support DocTypeGridEditor to Block Grid migration #66

13.1.0 (March 19th 2024)

• All items from 10.2.0-rc1

13.1.0-rc1 (March 5th 2024)

• Add legacy migrators and type resolver to allow importing from Umbraco 7 in #61

13.0.0 (December 14th 2023)

• Compatibility with Umbraco 13

Legacy release notes

You can find the release notes for versions out of support in the Legacy documentation on Github and Umbraco Deploy Package page

Once Umbraco Deploy has been installed and the schema data has been generated, a CI/CD build server needs to be set up.

The build server will extract the changes that has been pushed to the repository into your production website that has been connected with Umbraco Deploy.

This is something that can be done in many different ways depending on where your website is hosted and your setup.

Umbraco Deploy does not require the use of any particular build or deployment tools and hence we expect that you should be able to continue using the tool or tools of your choice. Any that have support for .NET website deployments and the running of Powershell scripts. such as Azure DevOps or Github Actions, would be appropriate.

Above and beyond the normal steps of a build pipeline for a .NET web application - tasks like NuGet restore, solution build, running of tests etc. - Umbraco Deploy requires three additional steps.

• The license file needs to be deployed into the target environment's umbraco/Licenses folder.

• The .uda schema files that are written to disk and included in source control, need to be made available in the build artifact that is deployed to the target environment.

• Once the build is complete, the extraction of the updated schema in the target environment needs to be triggered.

The first two steps will be implemented in a similar way. There will need to be a step added to the pipeline that runs after the main build of the website, to copy the license file and data files into the published build output, such that they are included in the build artifacts that are deployed to the target environment.

The third step needs to run last in the pipeline, once the built web application is deployed to the target environment. Umbraco Deploy provides a Powershell script that can be used for the purpose of triggering the extraction of the schema information and update of the target Umbraco installation.

Background on the Schema Extraction Process

Without a CI/CD pipeline step in place to trigger the extraction, following a deployment, the process would need to be carried out manually. This can be done by logging into the backoffice, navigating to Settings > Deploy and triggering the operation via the dashboard.

Behind the scenes what happens here is a marker file being written to disk - in the /umbraco/Deploy/ folder and with a name of deploy. It’s by monitoring this directory for a file with this name that Umbraco Deploy knows to trigger the extraction.

Umbraco Deploy also provides an HTTPS endpoint that can be called by an authenticated request. This will write the marker file, which will trigger the extraction.

Umbraco Deploy On-Premises also ships with a Powershell script, that when executed will call the endpoint, which will write the file, and which will trigger the extraction.

So while it may be possible to have the CI/CD step directly write the file or call the endpoint, so long as the build used supports running Powershell scripts this is the method we’d recommend, as it has some necessary error checking and retry logic built-in.

Details the setup of a CI/CD pipeline using Github Actions.

Details the setup of a CI/CD pipeline using Azure DevOps.

Umbraco Deploy is a deployment tool that helps you with the process of transferring code and data between multiple environments. Deploy can be configured for many different setups and is great for both small setups as well as large and more complex infrastructures.

Umbraco Deploy is also the engine that runs behind the scenes on Umbraco Cloud. Here it takes care of all the deployment processes of both code, schema and content on projects.

With Umbraco Deploy you get to use the Umbraco Cloud Deployment technology outside of Umbraco Cloud to ease deployment between multiple Umbraco environments. This is done by connecting external hosted Umbraco projects with a local instance of your Umbraco website.

In the Umbraco Deploy documentation can read all about how to set up and work with Umbraco Deploy.

You can find articles about how to set up Umbraco Deploy on a new or an existing website, and articles about the deployment workflow.

As with all of our products, it is always recommended to run the latest version of Umbraco Deploy.

On the Umbraco Deploy page in the you can see what the latest version is, as well as read the changelog.

Umbraco Deploy can be upgraded via NuGet.

Open the Package Console in Visual Studio and type:

Update-Package Umbraco.Deploy.OnPrem

You will be prompted to overwrite files. You should choose "No to All" by pressing "L" .

You can open the NuGet Package Manager and select the Updates pane to get a list of available updates. Choose the package called Umbraco.Deploy.OnPrem and click update. This will run through all the files and make sure you have the latest changes while leaving the files you have updated.

Contains version-specific documentation for when upgrading to new major versions of Umbraco Deploy.

This documentation platform covers only major versions of the Umbraco Deploy since Umbraco 9+. If you are using an older version of Umbraco Deploy, you will need to go elsewhere.

The documentation for Umbraco 7 and 8 lives on .

This page covers specific upgrade documentation for when migrating to major 13 of Umbraco Deploy.

Version Specific Upgrade Notes History

Version 13 of Umbraco Deploy has a minimum dependency on Umbraco CMS core of 13.0.0. It runs on .NET 8.

Breaking changes

Version 13 contains a number of breaking changes. We don't expect many projects to be affected by them as they are in areas that are not typical extension points. For reference though, the full details are listed here:

Behavior

• The default value for the configuration option ResolveUserInTargetEnvironment was changed to true.

Configuration

• Configuration of relations was changed from a list to a dictionary.

// Before
"RelationTypes": [
  {
    "Alias": "relateParentDocumentOnDelete",
    "Mode": "Weak",
  },
  {
    "Alias": "relateShopItemOnCreate",
    "Mode": "Exclude",
  }
],

// After
"RelationTypes": {
  "relateParentDocumentOnDelete": "Weak",
  "relateShopItemOnCreate": "Exclude"
},

• Configuration of value connectors was changed from a list to a dictionary.

// Before
"ValueConnectors": [
  {
    "Alias": "nuPickers.DotNetCheckBoxPicker",
    "TypeName": "Umbraco.Deploy.Contrib.Connectors.ValueConnectors.NuPickersValueConnector,Umbraco.Deploy.Contrib.Connectors",
  }
],

// After
"ValueConnectors": {
  "nuPickers.DotNetCheckBoxPicker": "Umbraco.Deploy.Contrib.Connectors.ValueConnectors.NuPickersValueConnector, Umbraco.Deploy.Contrib.Connectors"
},

Code

The following updates describe the more significant changes to the codebase and public API:

• Moved value connectors for core property editors from Umbraco.Deploy.Contrib into Umbraco.Deploy.Infrastructure.

• Renamed the Deploy add-on for Umbraco Forms from Umbraco.Deploy.Forms to Umbraco.Forms.Deploy.

These updates are more minor. We don't expect many projects to be affected by them as they are in areas that are not typical extension points:

• Removed the obsolete IsHeadless property from `UmbracoCloudClientConfigurationInfo``.

• Made the ProcessX methods for each step of content connectors private.

• Removed the obsolete overload of SaveContentType on ContentTypeConnectorBase.

• An obsolete constructor was removed from DictionaryItemConnector.

• QueueItemDto was moved into the Umbraco.Deploy.Infrastructure.Persistence namespace.

• DocumentConnector has a changed constructor such that we can use redirect tracking logic now exposed from CMS.

• Remove now unnecessary interfaces and extension methods for rich text parsing. These were introduced to ensure backward compatibility in older versions: IMacroParser2, IImageSourceParser2 and ILocaLinkParser2.

Legacy version specific upgrade notes

You can find the version specific upgrade notes for versions out of support in the Legacy documentation on Github.

Most configuration for Umbraco Deploy is provided via dotnet configuration. This is most often stored in the appsettings.json file found at the root of your Umbraco website. If the configuration has been customized to use another source, then the same keys and values discussed in this article can be applied there.

The convention for Umbraco configuration is to have package based options stored as a child structure below the Umbraco element, and as a sibling of CMS. Umbraco Deploy configuration follows this pattern, i.e.:

There are some required settings but most configuration for Umbraco Deploy is optional. In other words, values have defaults that will be applied if no configuration is available for a particular key.

For illustration purposes, the following structure represents the full set of options for configuration of Umbraco Deploy, along with the default values. This will help when you need to provide a different setting to understand where it should be applied.

Some configuration is applied via code rather than application settings. Where this is the case is also discussed in the sections to follow.

Configuration Via Application Settings

ApiKey or ApiSecret

The ApiKey is a random string (of at least 10 characters) set to the same value on all environments to authenticate HTTP requests between them. For improved security, set the ApiSecret to a cryptographically random value of 64 bytes instead (using Base64-encoding).

Edition

The default value for this setting is Default, which configures Umbraco Deploy to work according to how we expect most customers to use the product. Umbraco schema, such as Document and Data Types, are serialized to disk as .uda files in save operations. These are checked into source control and used to update the schema in the upstream environments via a trigger from your CI/CD pipeline, or automatically if using Umbraco Cloud.

Items managed by editors - content, media and optionally forms, dictionary items and members - are deployed between environments using the transfer and restore options available in the backoffice.

It is possible to use this method for all Umbraco data, by setting the value of this setting to BackOfficeOnly. With this in place, all data, including what is typically considered as schema, are available for transfer via the backoffice.

Our recommended approach is to leave this setting as Default and use source control and a deployment pipeline to ensure that structural changes to Umbraco are always aligned with the code and template amends that use them.

However, we are aware that some customers prefer the option to use the backoffice for all data transfers. If that is the case, the BackOfficeOnly setting will allow this.

ExcludedEntityTypes

This setting allows you to exclude a certain type of entity from being deployed. This is not recommended to set, but sometimes there may be issues with the way a custom media fileprovider works with your site and you will need to set it for media files. Here is an example:

RelationTypes

This setting allows you to manage how relations are deployed between environments. You will need to specify an alias and a mode for each relation type. The mode can be either:

• Exclude - This causes the relation to be excluded and not transferred on deployments.

• Weak - This causes the relation to be deployed if both content items are found on the target environment.

• Strong - This requires the content item that is related is set as a dependency, so if anything is added as a relation it would also add it as a dependency.

As of Deploy 10.1.2, 11.0.1 and higher, if this setting is left blank, the relation types used for usage tracking are omitted. These relations are rebuilt by the CMS following a save of an item in the target environment and so don't need to be transferred.

If a particular relation type is not listed, it's considered as a "weak" relation.

ValueConnectors

Here is an example of how the setting can look:

Timeout settings

Umbraco Deploy has a few built-in timeouts, which on larger sites might need to be modified. You will usually see these timeouts in the backoffice with an exception mentioning a timeout. It will be as part of a full restore or a full deployment of an entire site. In the normal workflow, you should never hit these timeouts.

There are four settings available relating to backoffice deployment operations:

• SessionTimeout

• SourceDeployTimeout

• HttpClientTimeout

• DatabaseCommandTimeout

These timeout settings default to 20 minutes, but if you are transferring a lot of data you may need to increase it.

A fifth timeout setting is available from Umbraco Deploy 9.5 and 10.1, allowing for the adjustment of the maximum time allowed for disk operations such as schema updates.

• DiskOperationsTimeout

This setting defaults to 5 minutes.

Batch settings

Even with appropriate settings of the above timeouts, Deploy's backoffice transfer operations can hit a hard limit imposed by the hosting environment. For Azure, this is around 4 minutes. This will typically only be reached if deploying a considerable amount of items in one go. For example, a media folder with thousands of items can reach this limit.

An error message of "The remote API has returned a response indicating a platform timeout" will be reported.

If encountering this issue, there are two batch settings that can be applied with integer values (for example 500). This will cause Deploy to transfer items in batches, up to a maximum size. This will allow each individual batch to complete within the time available. The higher the value, the bigger the batches.

• SourceDeployBatchSize - applies a batch setting for the transfer of multiple selected items to an upstream environment (such as a media folder with many images).

• PackageBatchSize - applies a batch setting to the processing of a Deploy "package", which contains all the items selected for a Deploy operation, plus all the determined dependencies and relations.

UseDatabaseBackedTransferQueue

In earlier versions of Umbraco Deploy, the transfer queue was implemented using in-memory storage. As a result, it would not be persisted across application restarts.

From 10.1, a database-backed queue was implemented and is used by default.

If for any reason there was a need to revert to the previous implementation, the value of this setting can be set to false.

TransferFormsAsContent

In order for Deploy to handle Forms data as content, you'll to ensure the TransferFormsAsContent setting is set to true. To transfer Forms data as schema, i.e. via .uda files committed to source control, use a value of false.

TransferDictionaryAsContent

In a similar way, Deploy can be configured to allow for backoffice transfers of dictionary items instead of using files serialized to disk, by setting TransferDictionaryAsContent as true.

Please see the note above under TransferFormsAsContent on the topic of removing any existing serialized files having changed this value to true.

IgnoreMissingLanguagesForDictionaryItems

When deploying dictionary items, an exception will be thrown if a translation is provided for a language that doesn't exist in the target environment.

Normally this is a useful fail-safe to ensure translations aren't lost in the transfer operation.

If you have deleted languages that have already existing translations, you may want to temporarily remove this check. You can do that by setting this value to true.

When this is in place a translation for a language that doesn't exist in the target environment will be ignored. A warning message will be output to the log.

SetEmptyDictionaryItemsOnTransfer

When deploying dictionary items, Umbraco Deploy follows the approach used for all content, emptying values that are transferred and set.

If you transfer a dictionary item with an empty translation to another environment that already contains a translation, it will be overwritten.

Set this value to false to not overwrite already populated values with empty strings.

AllowMembersDeploymentOperations and TransferMemberGroupsAsContent

It's also possible to transfer members and member groups via the backoffice between environments. This is disabled by default as a deliberate decision to make use of the feature needs to be taken, as for most installations it will make sense to have member data created and managed only in production. There are obvious potential privacy concerns to consider too. However, if being able to deploy and restore this information between environments makes sense for the specific workflow of your project, it's a supported scenario.

To enable, you can add or amend the AllowMembersDeploymentOperations and TransferMemberGroupsAsContent settings.

The AllowMembersDeploymentOperations setting can take four values:

• None - member deployment operations are not enabled (the default value if the setting is missing)

• Restore - restore of members from upstream environments via the backoffice is enabled

• Transfer - transfer of members to upstream environments via the backoffice is enabled

• All - restore and transfer of members from upstream environments via the backoffice is enabled

With TransferMemberGroupsAsContent set to true, member groups can also be transferred via the backoffice, and groups identified as dependencies of members being transferred will be automatically deployed.

Please see the note above under TransferFormsAsContent on the topic of removing any existing serialized files having changed this value to true.

ExportMemberGroups

This setting is to be defined and set to false only if you are using an external membership provider for your members. You will not want to export Member Groups that would no longer be managed by Umbraco but by an external membership provider.

Setting exportMemberGroups to false will no longer export Member Groups to .uda files on disk. The default for this setting is true, as most sites use Umbraco's built-in membership provider and thus will want the membership groups exported.

IgnoreBrokenDependenciesBehavior

When restoring or transferring content, Umbraco Deploy will make checks to ensure that any dependent content, media or other items are either present in the target environment, or can be deployed from the source environment.

For example, you may have a media picker on a content item, referencing media that has been deleted or is in the recycle bin. In this situation the dependency won't be available in the target environment.

Deploy can halt at this point, so you get an error and the deployment won't complete until the issue is resolved. To fix, you would need to remove the reference to the deleted media item.

Alternatively, you can configure Deploy to ignore these issues and proceed with the transfer operation without warning.

To configure the behavior you prefer, amend this value to either None, Transfer, Restore or All.

For example, using the following settings, you will have an installation that ignores broken dependencies when restoring from an upstream environment. It will however still prevent deployment and report any dependency issues when attempting a transfer to an upstream environment.

When configuring for Deploy 9, an additional IgnoreBrokenDependencies setting existed that took a value of true or false. To achieve the same result as the example above, the following configuration was required:

Memory cache reload

Some customers have reported intermittent issues related to Umbraco's memory cache following deployments, which are resolved by a manual reload of the cache via the Settings > Published Status > Caches dashboard. If you are running into such issues and are able to accommodate a cache clear after deployment, this workaround can be automated via the following setting:

By upgrading to the most recent available version of the CMS major you are running, you'll be able to benefit from the latest bug fixes and optimizations in this area. That should be your first option if encountering cache related issues. Failing that, or if a CMS upgrade is not an option, then this workaround can be considered.

Deployment of culture & hostnames settings

Culture and hostname settings, defined per content item for culture invariant content, are not deployed between environments by default. They can be opted into via configuration.

To enable this, set the configuration value as appropriate for the types of domains you want to allow:

• Culture - the language setting for the content, defined under "Culture"

• AbsolutePath - values defined under "Domains" with an absolute path, e.g. "/en"

• Hostname - values defined under "Domains" with a full host name, e.g. "en.mysite.com"

Combinations of settings can be applied, e.g. Hostname,AbsolutePath.

Deployment of public access settings

When deploying content items, public access rules based on member groups are transferred. You can amend this behavior using this setting.

• None - no public access rules will be transferred

• AddOrUpdate - public access rules added or updated in a source environment will be transferred to the destination

• Remove - public access rules removed a source environment will be removed in the destination

• All - all public access information will be transferred

AddOrUpdate is the default setting used if no value is configured.

Deployment of webhooks

Webhooks may be considered environment specific or schema information that you would like to synchronize between environments. As such, by default, Umbraco Deploy does not include webhooks in schema deployment operations.

If you would like you include them you can adjust this setting:

• None - webhooks are not deployed and are expected to be managed independently in each environment.

• All - webhooks included in schema deployments.

Deployment of trashed content

Specifies options for handling trashed content (documents, media and members) on export or import:

You can amend this behavior using this setting:

• None - trashed content will not be exported or imported

• Export - trashed content will be included in an export

• Import - trashed content will be processed and moved to the recycle bin on import

• All - trashed content will be included in an export, processed and moved to the recycle bin on import

PreferLocalDbConnectionString

When using Umbraco Deploy with Umbraco Cloud, a development database is automatically created when restoring a project into a local environment for the first time.

For Umbraco 10, by default, a SQLite database is created.

If you would prefer to use SQL Server LocalDb when it's available on your local machine, set this value to true. If LocalDB isn't reported as being available by Umbraco, it will fallback to using a SQLite database instead.

MediaFileChecksumCalculationMethod

Deploy will do comparisons between the entities in different environments to determine if they match and decide whether to include them in the operation. By default, for media files, a check is made on a portion of the initial bytes of the file.

This corresponds to the default setting of PartialFileContents.

If a lot of files need to be checked, this can be slow, and a faster option is available that uses the file metadata. The only downside of changing this option is a marginally increased chance of Deploy considering a media file hasn't changed when it has. This would omit it from the deployment.

To use this method, set the value to Metadata.

NumberOfSignaturesToUseAllRelationCache

When reviewing a set of items for a deployment operation, Deploy will retrieve and include relations. It does this either via single database lookups, or by bringing all relations into memory in one step, and retrieving them from there.

For small deployment operations, the former is the more optimal approach. It gets slow though when the number of items being transferred is large.

The cut-off before switching methods is set by this configuration value, and it defaults to an operation size of 100 items.

ContinueOnMediaFilePathTooLongException

When restoring between different media systems exceptions can occur due to file paths. They can happen between a local file system and a remote system based on blob storage. What is accepted on one system may be rejected on another as the file path is too long. Normally this will only happen for files with particularly long names.

If you are happy to continue without throwing exceptions in these instances you can set this value to true. For example, this may make sense if restoring to a local or development environment. If this is done such files will be skipped, and although the media item will exist there will be no associated file.

SuppressCacheRefresherNotifications

When a Deploy operation completes, cache refresher notifications are fired. These are used to update Umbraco's cache and search index.

In production this setting shouldn't be changed from it's default value of false, to ensure these additional data stores are kept up to date.

If attempting a one-off, large transfer operation, before a site is live, you could set this value to true. That would omit the firing and handling of these notifications and remove their performance overhead. Following which you would need to ensure to rebuild the cache and search index manually via the backoffice Settings dashboards.

ResolveUserInTargetEnvironment

With this setting assigned a value of true, Umbraco Deploy will attempt to resolve users when transfers are made to new environments.

Users and user groups are maintained separately in different environments, so it isn't always the case that an editor has accounts across all environments. When an account exists matching by email address, Deploy will associate the changes made in upstream environments with the user that initiated the transfer. Allowing the expected information about save and publish operations to be available in the audit log of the environment where the data was transferred.

When the setting is set to false, or a matching account isn't found, the audit records will be associated with the super-user administrator account.

Suspensions

Deploy operations suspend scheduled publishing, Examine indexing, document cache and/or signature database update events by default. You can amend this behavior for all supported or specific operations using these settings.

Each setting within this section represents a Deploy operation. For each, the suspensions that are carried out can be amended with one or more of following values:

• DiskRead - None, ScheduledPublishing, Examine, DocumentCache, All,

• PartialRestore - None, ScheduledPublishing, Examine, DocumentCache, All,

• Restore - None, ScheduledPublishing, Examine, DocumentCache, Signatures, All,

• Deploy - None, ScheduledPublishing, All,

• Import - None, ScheduledPublishing, Examine, DocumentCache, All,

• Export - None, ScheduledPublishing, All

The default value for all suspension settings is All.

So for example if you wanted to remove Examine indexing suspension and resumption during partial restore operations, you could set the following:

It's also possible to set the values for all operations by setting Suspensions to a value instead of an object, for example:

If you prefer configuration in code, operators overloads on the settings class make this process straightforward, as shown in the following example:

HideConfigurationDetails

If set to true the configuration details shown on the setting's dashboard will be hidden.

HideVersionDetails

If set to true the version details shown on the setting's dashboard will be hidden.

Configuration Via Code

Webhook Events

Umbraco Deploy can optionally register events that you can use with Umbraco webhooks. You can add them via code, for which we provide an extension method. The following example shows how you can use this within a composer.

With that in place you should see two new events available that you can use in creating your webhooks.

• Deploy operation was completed

• Deploy operation failed

An example of the payload sent is shown below:

In this article you can learn more about what it takes to get started using Umbraco Deploy. You can also get a high-level overview of how the product works.

How Umbraco Deploy works

Umbraco Deploy works by serializing non-content Umbraco items (called “Schema” items) to disk. These serialized files are located in the /umbraco/Deploy/Revision folder at the root of your website.

These items are entities like Document Types, Media Types, Data Types, etc, and these files must be committed to source control (for example Git). Umbraco Deploy works by “extracting” this serialized information back into your Umbraco installation. This is done by deployment triggers when a deployment is sent to a target environment.

For example, when working locally you might create a new Document Type. This will automatically create a new on-disk file in the umbraco/Deploy/Revision folder which is the serialized version of the new Document Type. You would then commit this file to your repository and push this change to your hosted source control (for example GitHub).

When you want this deployed to your next environment, you would trigger your CI/CD process (for example Azure DevOps or Github Actions). This will push the changes to your environment. Once the build deployment completes successfully, a Deployment Trigger would be executed as an HTTPS request to your target environment. All changes found in the umbraco/Deploy/Revision folder will then be extracted into the Umbraco target environment.

There are three main steps you need to go through in order to start using Umbraco Deploy on your website.

1. • Set up a repository and then install a new Umbraco project inside it.

2. • Umbraco Deploy can be installed via NuGet.

3. • Umbraco Deploy needs a CI/CD build server needs to be set up to run when you want changes to be deployed to next upstream environment

Prerequisites

Ensure to first read and follow the setup guides for either new or existing projects below:

Source Control Configuration

After the Umbraco files have been committed add the following lines to the .gitignore so that they will not be picked up by Git when we are deploying.

Make sure that the updates to the .gitignore file are also committed.

Installing and Configuring Umbraco Deploy

When Umbraco has been installed in a repository, we can install Umbraco Deploy in the project.

To install Umbraco Deploy, run dotnet add package Umbraco.Deploy.OnPrem from the command line or Install-Package Umbraco.Deploy.OnPrem from the package manager console in Visual Studio.

With Umbraco Deploy installed, to use it in the project you will need to create and add configuration for an API key/secret.

For improved security, it is recommended to set the ApiSecret (instead of the ApiKey) setting to a cryptographically random value of 64 bytes. Using Base64-encoding to get the string representation, will result in a value of 88 characters. For versions prior to Deploy 12 or when not using the API secret setting, the recommendation is to set the ApiKey to a randomly generated string of 64 characters.

Configuring Environments

Once the API secret has been added, it is now time to configure the environments, also in the appsettings.json file.

An example configuration with a single upstream environment file will look like this:

The setting under Project:CurrentWorkspaceName should match the Name provided in the list of Workspaces that match the current environment. Using this Umbraco Deploy will indicate the correct current environment on the "Workspaces" dashboard.

Expected values for Type are "development", "staging" or "live". These settings are required, though strictly only for the latter is it necessary to use the specific value of "live", so other values can be used if you have more than these three environments.

You will need to generate a unique GUID for each environment. This can be done in Visual Studio:

1. Open "Tools".

2. Select "Create GUID".

3. Use the Registry Format.

4. Copy the GUID into the id value.

5. Generate a "New GUID" for each environment you will be adding to your setup.

Or by running the following PowerShell command:

The URL configured for each environment should be the root URL for the website and needs to be accessible by the other environments over HTTPS.

Validating Source Control

Once the configuration has been set up with the correct information we can now go ahead and make sure that the source control is including our files in the /umbraco/Deploy folder of our Umbraco project.

This can be done by going to the /umbraco/Deploy/Revision folder of the project and create a test .uda file, and then check in either your Git GUI or in the command line and verify whether the test file is being tracked.

We can see that the file has been created and it is being tracked by Git and we can go ahead and delete the test file.

Now that Umbraco Deploy has been installed on the project, we can go ahead and commit the files to the repository.

Do not push the files up yet as a CI/CD build server will first need to be set up and connected to our repository.

Include your Umbraco Deploy license file

Before moving on to setting up the build server, make sure that your license is included in your project.

For Umbraco Deploy On-Premise, this will be a key provided to you when taking out your subscription to the product. It should be added to your configuration at the key Umbraco:Licenses:Umbraco.Deploy.OnPrem.

For example, in appsettings.json:

Umbraco Cloud projects use a license file placed in the /umbraco/Licenses folder that is provided when your project is created.

Umbraco Deploy uses a deployment model that relies on Git and Umbraco Deploy core technology to move your changes from one environment to another. Umbraco Deploy uses a classic "left to right" deployment model, meaning that changes are first made in the Development or local environment and then deployed to the production environment.

Deployment Approach

Umbraco Deploy uses a two-part deployment approach where we keep meta data (Document types, templates, etc) and content (Content nodes and Media) as separate parts of a deployment. In order to be able to distinguish between the two types of deployments we use the term transfer for content and media deployments and the term deploy for meta data deployments.

In summary:

1. Meta data such as Document Types, Templates, Forms, Views and config files are stored in a repository and are deployed between environments. This can be achieved using a CI/CD deployment pipeline with something like Github Actions or Azure DevOps.

2. Content and Media items are not stored in the repository. These need to be transferred directly from the Umbraco backoffice using the "Queue for Transfer" option. Once a content editor has all the items needed for a transfer they will use the Deployment Dashboard in the Content section to transfer the items in the queue.

Deploying meta data

In order to be able to transfer content and media, the source environment and the target environment needs to have the same setup - meaning they need to be completely in sync and have the same file structure. To achieve this you need to deploy your meta data changes to the target environment.

Transfer Content and Media

Moving your content and media between your environments is done through the Umbraco backoffice. You can transfer content from one environment to another, e.g. from local to your development environment. You also have the option to restore content and media to your local or development environment from your production or staging environment.

Import and Export

Another approach for transferring content and schema between environments is to use import and export. In one environment, you can export selected content, a tree, or the whole workspace to a .zip file. There are options to include related media files, schema and code files such as templates and stylesheets.

That .zip file can then be uploaded into a new environment, where it will be validated and then processed to update Umbraco.

As part of the import process, we provide hooks to allow for migrations of the imported artifacts (like data types) and property data. This should allow you to migrate your Umbraco data from one Umbraco major version to a newer one.

We recommend using the content and media backoffice transfer options for day-to-day editorial activities. Import and export is intended more for larger transfer options, project upgrades, or one-off tasks when setting up new environments.

Deploy Dashboard

In Umbraco Deploy we have included a Deploy Dashboard in the Settings section of the Umbraco backoffice to make it easier to run operations like schema deployment from data files and extract schema to data files.

When running the extract schema to data files operation, Umbraco Deploy will run an echo > deploy-export in the data folder of your project which is used to generate UDA files based on the schema in your database.

Running the schema deployment from data files operation will initiate an extraction on the environment

The extraction will end in one of two possible outcomes:

1. deploy-complete: The extraction succeeded and your environment is in good shape!

2. deploy-failed: The extraction failed - open the deploy-failed file, to see the error message.

It is also possible to see which version of Umbraco Deploy you are running, when the last operation was started and the status of the deployment operation.

In this section, we provide a full example of how Umbraco Deploy running on Umbraco 9 and above can be utilized. This can be used as a part of a build and deployment pipeline using Azure DevOps. You can use this directly or adapt it for your needs.

Discussion on the Provided Example

We have defined a single stage build and deployment pipeline, configured in YAML format. While not as visually intuitive as a drag-and-drop task list, it provides the advantage of source control management.

We then have a number of variables defined, that are used in the build configuration below. By using variables we have the ability to modify the script for use on other web applications. Some values are set in the script, and some via Azure DevOps variables or secrets.

Most tasks in the pipeline are standard steps that will be used in any .NET web application release, such as the first steps:

#1 Install of the NuGet tooling,

#2 Restore of NuGet dependencies,

#3 And the project build.

Additional steps can be added as required, for example for running automated tests.

The Umbraco Deploy license file and the schema data files will automatically be included within the build output.

The deployment part of the pipeline stage consists of two steps.

Firstly a web deployment (#4), takes the packaged build artifact and deploys it, in this case, to an Azure Web App slot.

The final step (#5) is Umbraco Deploy specific - to call a function defined in the PowerShell script and trigger the extraction. Replace ApiSecret with ApiKey if you're using the deprecated API key setting instead.

Full Example

In this section we discuss some additional steps you can carry out to streamline your local development workflow.

Creating Git Hooks

Working in a team, it's common for developers to pull code from source control to update their local environment with the latest Umbraco schema.

They can do this by starting up the website, navigating to the Settings > Deploy dashboard and triggering a data extraction.

We can automate this step using a git hook.

When working with Umbraco Cloud, this step is configured automatically for you when you clone and run your project the first time. If working with Umbraco Deploy On-Premise, you can set it up yourself.

The process works by using the marker file Umbraco Deploy uses to trigger an update of the Umbraco schema from the .uda files from source control.

If a file named deploy-on-start is found in the /umbraco/Deploy folder, an update will run automatically when the site starts up.

Therefore, if we ensure that the file is created everytime the source code is pulled from the remote repository, we can automate the update.

To do this, carry out the following steps:

• Find the .git folder within your solution root.

  • It might be a hidden folder, so if you don't see it, make sure your file browser is configured to show hidden files and folders.

• Within that you'll find a hooks folder, and inside that, a file called post-merge.sample.

• Rename the file to remove the .sample extension and open it in a text editor.

• Apply the following text and save the file (amending the path to the web project as appropriate for your solution structure):

#!/bin/sh
echo > src/UmbracoProject/umbraco/Deploy/deploy-on-start

• Run a git pull origin <branchname>.

• Start up the website and you should find the Umbraco schema update has been triggered.

The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from the backoffice or use the service.

However, you can still use this feature to help migrate from Umbraco 7 to a supported major version. This requires adding additional logic to your Umbraco 7 project to create an export ZIP archive similar to newer versions.

Exporting Umbraco 7 content and schema

You can generate an export archive in the same format as the import/export feature. This is done by adding the Umbraco.Deploy.Contrib.Export assembly to your Umbraco 7 project (that already has Deploy and Deploy Contrib installed, see below). This archive can be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.

This is possible via code, by temporarily applying a composer to an Umbraco 7 project to generate the export archive on start-up:

using System;
using System.Linq;
using System.Web.Hosting;
using Umbraco.Core;
using Umbraco.Deploy;
using UmbracoDeploy.Contrib.Export;

public class DeployExportApplicationHandler : ApplicationEventHandler
{
    protected override void ApplicationInitialized(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
    {
        // Set a default value connector that doesn't use object type prefixes
        DefaultValueConnector.SetDefault();

        // Run export after Deploy has started
        DeployComponent.Started += (sender, e) => DeployStarted();
    }

    protected void DeployStarted()
    {
        var udis = new[]
        {
            // Export all content
            Constants.UdiEntityType.Document,
            Constants.UdiEntityType.DocumentBlueprint,
            Constants.UdiEntityType.Media,
            // Export all forms data
            Constants.UdiEntityType.FormsForm,
            Constants.UdiEntityType.FormsDataSource,
            Constants.UdiEntityType.FormsPreValue
        }.Select(Udi.Create);

        var dependencyEntityTypes = new[]
        {
            // Include all related schema
            Constants.UdiEntityType.DataType,
            Constants.UdiEntityType.DataTypeContainer,
            Constants.UdiEntityType.DocumentType,
            Constants.UdiEntityType.DocumentTypeContainer,
            Constants.UdiEntityType.MediaType,
            Constants.UdiEntityType.MediaTypeContainer,
            Constants.UdiEntityType.MemberType,
            Constants.UdiEntityType.MemberGroup,
            Constants.UdiEntityType.Macro,
            Constants.UdiEntityType.DictionaryItem,
            Constants.UdiEntityType.Template,
            Constants.UdiEntityType.Language,
            // Include all related files
            Constants.UdiEntityType.MediaFile,
            Constants.UdiEntityType.MacroScript,
            Constants.UdiEntityType.PartialView,
            Constants.UdiEntityType.PartialViewMacro,
            Constants.UdiEntityType.Script,
            Constants.UdiEntityType.Stylesheet,
            Constants.UdiEntityType.UserControl,
            Constants.UdiEntityType.TemplateFile,
            Constants.UdiEntityType.Xslt
        };

        // Create export
        var zipArchiveFilePath = HostingEnvironment.MapPath("~/data/" + "export-" + Guid.NewGuid() + ".zip");
        ArtifactExportService.ExportArtifacts(udis, Constants.DeploySelector.ThisAndDescendants, zipArchiveFilePath, dependencyEntityTypes);
    }
}

Importing Umbraco 7 content and schema

To import this archive into a newer Umbraco project, you need to install either of these packages:

• UmbracoDeploy.Contrib 4.3 for Umbraco 8

• Umbraco.Deploy.Contrib for Umbraco 10.2, 12.1, 13.1 or later

Then you need to configure the legacy artifact type resolver and migratory.

Artifact type resolvers allow resolving changes in the type that's stored in the __type JSON property of the artifact. This is in case it moved to a different assembly or namespace (or got renamed) in a newer version. The legacy migrators handle the following changes:

• Moving the pre-values of data types to the configuration property;

• Moving the invariant release and expiration dates of content to the (culture variant) schedule property;

• Moving the 'allowed at root' and 'allowed child content types' of content/media/member types to the permissions property;

• Migrating the Data Type configuration from pre-values to the correct configuration objects and new editor aliases for:

  • Umbraco.CheckBoxList (pre-values to value list)

  • Umbraco.ColorPickerAlias to Umbraco.ColorPicker (pre-values to value list)

  • Umbraco.ContentPicker2 to Umbraco.ContentPicker (removes invalid start node ID)

  • Umbraco.ContentPickerAlias to Umbraco.ContentPicker (removes invalid start node ID)

  • Umbraco.Date to Umbraco.DateTime

  • Umbraco.DropDown to Umbraco.DropDownListFlexible (pre-values to value list, single item select)

  • Umbraco.DropDownListFlexible (pre-values to value list, defaults to multiple item select)

  • Umbraco.DropdownlistMultiplePublishKeys to Umbraco.DropDownListFlexible (pre-values to value list, defaults to multiple item select)

  • Umbraco.DropdownlistPublishingKeys to Umbraco.DropDownListFlexible (pre-values to value list, defaults to single item select)

  • Umbraco.DropDownMultiple to Umbraco.DropDownListFlexible (pre-values to value list, defaults to multiple item select)

  • Umbraco.MediaPicker2 to Umbraco.MediaPicker (removes invalid start node ID, defaults to single item select)

  • Umbraco.MediaPicker (removes invalid start node ID)

  • Umbraco.MemberPicker2 to Umbraco.MemberPicker

  • Umbraco.MultiNodeTreePicker2 to Umbraco.MultiNodeTreePicker (removes invalid start node ID)

  • Umbraco.MultiNodeTreePicker (removes invalid start node ID)

  • Umbraco.MultipleMediaPicker to Umbraco.MediaPicker (removes invalid start node ID, defaults to multiple item select)

    • Umbraco.NoEdit to Umbraco.Label

  • Umbraco.RadioButtonList (pre-values to value list, change database type from integer to nvarchar)

  • Umbraco.RelatedLinks2 to Umbraco.MultiUrlPicker

  • Umbraco.RelatedLinks to Umbraco.MultiUrlPicker

  • Umbraco.Textbox to Umbraco.TextBox

  • Umbraco.TextboxMultiple to Umbraco.TextArea

  • Umbraco.TinyMCEv3 to Umbraco.TinyMCE

• Migrating pre-value property values for:

  • Umbraco.CheckBoxList

  • Umbraco.DropDown.Flexible

  • Umbraco.RadioButtonList

The following composer adds the required legacy artifact type resolver and migrators. It also adds a custom resolver that marks the specified Document Type alias testElement as the element type. Element types are a concept added in Umbraco 8 and are required for Document Types that are used in Nested Content.

using Umbraco.Cms.Core.Composing;
using Umbraco.Deploy.Contrib.Migrators.Legacy;

internal class LegacyImportComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactTypeResolvers()
            .AddLegacyTypeResolver();

        builder.DeployArtifactMigrators()
            .AddLegacyMigrators()
            .Append<ElementTypeArtifactMigrator>();

        builder.DeployPropertyTypeMigrators()
            .AddLegacyMigrators(); // Available from Deploy Contrib 13.3.0 and 14.2.0+
    }

    private class ElementTypeArtifactMigrator : ElementTypeArtifactMigratorBase
    {
        public ElementTypeArtifactMigrator()
            : base("testElement")
        { }
    }
}

Obtaining Umbraco Deploy for Umbraco 7

Umbraco Deploy for Umbraco 7 is no longer supported and was only available on Umbraco Cloud. It was not released for use on-premise.

As such if you are looking to migrate from an Umbraco Cloud project running on Umbraco 7, you already have Umbraco Deploy installed.

If you have an Umbraco 7 on-premises website, you can use this guide to migrate from on-premises to Umbraco Cloud. Or to upgrade to a newer Deploy On-premises version. You need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.

The export feature can be used without a license.

Use this guide to migrate from on-premises to Umbraco Cloud or to upgrade to a newer Deploy On-premises version.

1. Download the required dll files for Umbraco Deploy for Umbraco 7 from the following links:

• Umbraco Deploy v2.1.6: Latest Deploy Version 2 release for Umbraco CMS Version 7 (officially for use on Cloud)

• Umbraco Deploy Contrib v2.0.0: Latest/only Deploy Contrib Version 2

• Umbraco Deploy Export v2.0.0: For exporting all content/schema in Version 7

1. Install Umbraco Deploy with the Contrib and Export extensions.

• Install Umbraco Deploy, Deploy.Contrib, and Deploy.Export by copying the downloaded .dll files into your Umbraco 7 site.

• When copying the files over from Umbraco Deploy you should not overwrite the following files (if you already had Umbraco Deploy installed):

 Config/UmbracoDeploy.config
 Config/UmbracoDeploy.Settings.config

• Run the project to make sure it runs without any errors

1. Update the web.config file with the required references for Umbraco Deploy:

<?xml version="1.0"?>
<configSections>
    <sectionGroup name="umbraco.deploy">
      <section name="environments" type="Umbraco.Deploy.Configuration.DeployEnvironmentsSection, Umbraco.Deploy" requirePermission="false" />
      <section name="settings" type="Umbraco.Deploy.Configuration.DeploySettingsSection, Umbraco.Deploy" requirePermission="false" />
    </sectionGroup>
  </configSections>
  <umbraco.deploy>
    <environments configSource="config\UmbracoDeploy.config" />
    <settings configSource="config\UmbracoDeploy.Settings.config" />
  </umbraco.deploy>
</configuration>

1. Export Content.

• Export your content, schema, and files to zip.

In this article you can learn more about how to deploy your code changes and meta data from a local instance to a remote environment.

Deploying from local to your environments

When you are working with your Umbraco project locally all changes you make will automatically be identified and picked up by your local Git client.

Here's a quick step-by-step on how you deploy these changes to your environment:

• You've cloned a site to your local machine to work on.

• You've made some changes to a Document Type.

• The corresponding .uda file for this Document Type is now updated with the changes - the file is located in the /umbraco/Deploy/Revision folder.

• You've also created a new Data Type that's used on the Document Type. This Data Type is stored as a new file in the /umbraco/Deploy/Revision folder as well.

• Using Git, commit those two changed files to your local repository and push them to your repository.

• A deployment kicks in and the Document Type is updated and the new Data Type you created locally is now automatically created in the remote environment as well.

Deploying without using a Git client

If you don't have a Git client installed on your local machine, you can use Git or Git Bash for command-line Git operations. Run the following commands:

# Navigate to the repository folder
cd mySite
# Check status of the repository for pending changes
git status
# Add pending changes
git add -A
# Commit staged files
git commit -m "Adding updated schema changed"
# Push to the environment
git push

# If the push is rejected you will need to pull first
git pull
# Try to push again if there were no conflicts
git push

When pulling new commits, it is a good idea to see if any of these commits contained changes to the schema (anything in umbraco/Deploy/Revision/). To ensure your local schema is up-to-date, you can navigate to the umbraco/Deploy/ folder and create a deploy marker if it doesn't exist. From a command line type the following command:

/…mysite/umbraco/Deploy> echo > deploy

The local site should be running when you do this. The deploy marker will change to deploy-progress while updating the site and to deploy-complete when done. If there are any conflicts/errors you will see a deploy-failed marker instead, which contains an error message with a description of what went wrong.

Another way is to use the Deploy Dashboard in the Settings section of the Umbraco backoffice. Here you can see the status of ongoing or completed deployment processes. The status will show whether an operation has been triggered and whether it is in progress, has completed or has failed. The dashboard will show the status based on the marker files on the disk, eg. deploy-progress. From the Deploy Dashboard it is also possible to trigger processes. Learn more about this dashboard in the Deployment article.

As well as importing the content and schema directly, we also provide support for modifying the items as part of the process.

For example, you may have taken an export from an Umbraco 8 site, and are looking to import it into a newer major version. In this situation, most content and schema will carry over without issue. However, you may have some items that are no longer compatible. Usually this is due to a property editor - either a built-in Umbraco one or one provided by a package. These may no longer be available in the new version.

Often though there is a similar replacement. Using Deploy's import feature we can transform the exported content for the obsolete property into that used by the new one during the import. The migration to a content set compatible with the new versions can then be completed.

For example, we can migrate from a Nested Content property in Umbraco 8 to a Block List in Umbraco 13.

We provide the necessary migration hooks for this to happen, divided into two types - artifact migrators and property migrators.

Artifact migrators

Artifact migrators work by transforming the serialized artifact of any imported artifact, via two interfaces:

• IArtifactMigrator - where the migration occurs at the artifact property level

• IArtifactJsonMigrator - where the migration occurs at the lower level of transforming the serialized JSON itself.

Implementations to handle common migrations of Data Types from obsoleted property editors are available:

• ReplaceMediaPickerDataTypeArtifactMigrator - migrates a Data Type from using the legacy Media Picker to the current version of this property editor

• ReplaceNestedContentDataTypeArtifactMigrator - migrates a Data Type based on the obsolete Nested Content property editor to the Block List

• ReplaceGridDataTypeArtifactMigrator - migrates a Data Type based on the legacy Grid layout into the Block Grid

• ReplaceUnknownEditorDataTypeArtifactMigrator - replaces any unknown editor alias with a label

We've also made available base implementations that you can use to build your own migrations. You may need to handle the transfer of information between other obsolete and replacement property editors that you have in your Umbraco application.

• ArtifactMigratorBase<TArtifact> - migrates the artifact of the specified type

• DataTypeArtifactMigratorBase - migrates Data Type artifacts

• ReplaceDataTypeArtifactMigratorBase - migrates a Data Type from one property editor to another

• ArtifactJsonMigratorBase<TArtifact> - migrates the JSON of the specified artifact type

• ReplaceGridDataTypeArtifactMigratorBase - migrates a Data Type based on the legacy Grid layout into the Block Grid

Property migrators

Property migrators work to transform the content property data itself. They are used in the Deploy content connectors (documents, media and members) when the property editor is changed during an import:

Again we have an interface:

• IPropertyTypeMigrator

Implementations for common migrations:

• MediaPickerPropertyTypeMigrator

• NestedContentPropertyTypeMigrator

• GridPropertyTypeMigrator

And a base type to help you build your own migrations:

• PropertyTypeMigratorBase

• GridPropertyTypeMigratorBase

Registering migrators

Migrators will run if you have registered them, so you can enable only the ones needed for your solution.

You can do this via a composer, as in the following example. Here we register two of the migrators shipped with Umbraco Deploy:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Deploy.Infrastructure.Migrators;
using Umbraco.Extensions;

internal class ArtifactMigratorsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactMigrators()
            .Append<ReplaceNestedContentDataTypeArtifactMigrator>()
            .Append<ReplaceMediaPickerDataTypeArtifactMigrator>();

        builder.DeployPropertyTypeMigrators()
            .Append<NestedContentPropertyTypeMigrator>()
            .Append<MediaPickerPropertyTypeMigrator>();
    }
}

Import and migration flow

When an import is started, the following happens:

1. Artifact signatures are read from the import provider (using IArtifactImportProvider.GetArtifactSignatures()).

2. The artifact signatures are sorted based on dependencies with Ordering enabled (ensuring dependent items are processed in the correct order, like parent items before children and data types before document types).

3. For each artifact signature:

   1. Check whether the entity type is allowed to be imported.

   2. Publish an ArtifactImportingNotification (cancelling will skip importing the artifact).

4. Publish a ValidateArtifactImportNotification:

   • Deploy adds a default handler (ValidateArtifactImportDependenciesNotificationHandler) to validate whether all dependencies are either in the import or already present in the current environment. It emits warnings for missing content artifacts, missing or different artifact checksums and errors for missing schema artifacts.

   • The import fails on validation errors or 'soft' fails on warnings if the WarningsAsErrors import option is set.

5. Create a Deploy scope and context (containing the 'owner' user for auditing purposes and cultures to import, in case the user doesn't have edit permissions for all languages).

6. For each artifact signature:

   1. Create a (readonly) Stream for the artifact (using IArtifactImportProvider.CreateArtifactReadStream(Udi)).

   2. Deserialize the artifact into a generic JSON object (JToken).

   3. Parse the __version and __type properties and resolve the artifact type (using IArtifactTypeResolver).

   4. Migrate the JSON object (using IArtifactJsonMigrator).

   5. Deserialize the JSON object into the artifact type.

   6. Migrate the artifact (using IArtifactMigrator).

   7. Initialize artifact processing (using IServiceConnector.ProcessInit(...)) and track deploy state with next passes.

7. For each next process pass (starting at the lowest initial next pass):

   1. Process artifact (using IServiceConnector.Process(...)).

   2. During processing: service connectors for content, media and members migrate property type values if a property editor alias has changed (using IPropertyTypeMigrator).

   3. When no next pass is required (the deploy state returns -1 as next pass):

      1. Publish an ArtifactImportedNotification.

      2. Report the import process (using IProgress.Report(...)).

8. The Deploy scope is completed, causing all scoped notifications to be published to handlers implementing IDistributedCacheNotificationHandler) and completing the import.

Details of Specific Migrations

Umbraco Deploy ships with migrators to handle the conversion of core property editors as they have changed, been removed or replaced between versions.

Open source migrators may be built by HQ or the community for property editors found in community packages. They will be made available for use and review via the Umbraco.Deploy.Contrib package.

Grid to Block Grid

The Grid editor introduced in Umbraco 7 can still be used in version 13 but has been removed from Umbraco 14. Its functionality is replaced with the Block Grid editor.

With Deploy migrators we have support for migrating Data Type configuration and property data between these property editors.

You can configure the default migration with the following composer:

using Umbraco.Cms.Core.Composing;
using Umbraco.Deploy.Infrastructure.Migrators;

internal sealed class DeployMigratorsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactMigrators()
            .Append<ReplaceGridDataTypeArtifactMigrator>();

        builder.DeployPropertyTypeMigrators()
            .Append<GridPropertyTypeMigrator>();
    }
}

These implementations make use of the following conventions to migrate the data:

• ReplaceGridDataTypeArtifactMigrator:

  • Grid layouts are migrated to an existing or new element type with an alias based on the layout name, prefixed with gridLayout_ (this can be customized by overriding MigrateGridTemplate());

  • Row configurations are migrated to an existing or new element type with an alias based on the row name, prefixed with gridRow_ (this can be customized by overriding MigrateGridLayout());

  • Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with gridEditor_ (this can be customized by overriding MigrateGridEditor()). The available editors are retrieved from the grid.editors.config.js files (can be overridden in GetGridEditors()). Each migrated grid editor will have the following property types added to the element type:

    • The media grid editor is migrated to multiple properties: the value property contains the selected media item (using Media Picker v3), altText the alternate text (using a Textbox) and caption the caption (also using a Textbox);

    • The remaining grid editors create a single value property that uses the following editors:

      • rte - the default 'Rich Text Editor', falling back to the first Umbraco.TinyMCE editor.

      • headline - the default 'Textstring', falling back to the first Umbraco.TextBox editor.

      • macro and embed grid editors are converted into rich text editors.

      • quote or any other - use falling back to the first Umbraco.TextArea editor.

    • The block label is also updated for the built-in grid editors, ensuring a nice preview is available (the WYSIWYG style previews are incompatible between these editors, so the custom views are not migrated);

  • Grid settings config and styles are migrated to a new element type with a random alias, prefixed with gridSettings_ (this can be customized by overriding MigrateGridSettings()). This is because the migration only has context about the Data Type configuration (not the actual Data Type) and multiple Data Type can potentially use the same configuration (for config and styles), so there's no predictable way to create a unique alias. The migrated settings element type will have the property types added for the config and styles:

    • Each config setting is migrated to a property with an alias based on the key, prefixed with setting_ and added below a 'Settings' property group;

    • Similarly, each style is migrated to a property with an alias based on the key, prefixed with style_ and added below a 'Styles' property group;

    • The following property editors are used for these properties based on the config/style view:

      • radiobuttonlist - a new 'Radio Button List' Data Type that uses the pre-values;

      • multivalues - a new 'Checkbox List' Data Type that uses the pre-values;

      • textstring - the default 'Textstring', falling back to the first Umbraco.TextBox editor.

      • mediapicker and imagepicker - the default 'Media Picker' (v3, single image), falling back to the first Umbraco.MediaPicker3 editor.

      • boolean - the default 'Checkbox', falling back to the first Umbraco.TrueFalse editor.

      • number - the default 'Numeric', falling back to the first Umbraco.Integer editor.

      • treepicker, treesource, textarea or any other - the default 'Textarea', falling back to the first Umbraco.TextArea editor.

• GridPropertyTypeMigrator:

  • Gets the grid layout and row configuration element types based on the alias prefix/name convention used by the Data Type artifact migrator;

  • The grid editor values are migrated to the respective properties:

    • The media grid editor converts the value to a media item with crops (based on the UDI or media path), including the focal point (although this needs to be enabled on the Data Type), alternate text and caption;

    • All other values are converted to a text value or otherwise to a JSON string;

  • If a row or cell contains settings config or styles and the corresponding block has a settings element type configured, the settings config and styles are migrated to their respective properties in a similar way, based on the property editor alias:

    • Umbraco.MediaPicker3 - removes url(' from the beginning and ') from the end of the value (commonly used as a modifier and added to the stored value), before trying to get the media item by a path.

    • All other values are returned as-is.

Given the flexibility of the grid editor and Block Grid you may want to take further control over the migration. You can do that by creating your own migrator classes, that make use of our provided base classes. You would then register your own migrators instead of the ones shipped with Umbraco Deploy in your composer.

The base classes provide the following functionality. Methods you should look to override to amend the default behavior have been noted above.

• ReplaceGridDataTypeArtifactMigratorBase - replaces the Umbraco.Grid Data Type editor alias with Umbraco.BlockGrid and migrates the configuration:

  • The number of columns is copied over.

  • Grid layouts, row configurations and grid editors are migrated to blocks:

    • If multiple grid layouts are configured or if at least one contains multiple sections or isn't the full width, each grid layout will be migrated to a 'layout block' (an element type without properties).

    • If multiple row configurations are configured or if at least one contains areas that don't allow all grid editors or has a maximum amount of items set, each row configuration is migrated to a block (this is also always done when there are multiple grid layouts, as each layout can configure allowed row configurations).

    • All grid editors are migrated to blocks (allowing a single grid editor to be migrated to multiple blocks to support DocTypeGridEditor, as that allows selecting different element types).

  • The settings config and styles are migrated to a single element type (even though each setting can define whether it's supported for rows and/or cells) and used on the blocks that are allowed.

  • Block groups are added for Layout and Content and used on the corresponding block types.

• GridPropertyTypeMigratorBase - migrates the property data from the GridValue into the BlockValue (using the Umbraco.BlockGrid layout):

  • The related Data Type is retrieved to get the configured blocks.

  • All grid control values are first migrated into their content blocks.

  • Settings config and styles for 'grid cells' are stored on the area within a row, but areas in the Block Grid can't have settings, so this is migrated into the first migrated grid control content block instead.

  • If a layout block can be found for the row configuration name, all grid controls are wrapped into that block.

  • Similarly, if a layout block can be found for the grid layout name, all items are wrapped into that block.

  • The JSON serialized BlockValue is returned.

Migrating From Doc Type Grid Editor

Doc Type Grid Editor was a community package commonly used with the legacy grid editor. If you are using this with Umbraco 7 and up, you can export and migrate into the Block Grid on Umbraco 13 or above.

Ensure you are running the latest version of Umbraco.Deploy.Contrib compatible with your Umbraco major version.

In your new project, register the following migrators to add support for the import from Doc Type Grid Editor grids:

using Umbraco.Cms.Core.Composing;
using Umbraco.Deploy.Infrastructure.Migrators;

internal sealed class DeployMigratorsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactMigrators()
            .Append<ReplaceDocTypeGridEditorDataTypeArtifactMigrator>();

        builder.DeployPropertyTypeMigrators()
            .Append<DocTypeGridEditorPropertyTypeMigrator>();
    }
}

The migrators add the following behavior:

• ReplaceDocTypeGridEditorDataTypeArtifactMigrator extends ReplaceGridDataTypeArtifactMigrator and ensures any DocTypeGridEditor is migrated to blocks using the allowed element types. If the element types aren't found the default implementation will migrate to new element types.

• DocTypeGridEditorPropertyTypeMigrator extends GridPropertyTypeMigrator and ensures the Doc Type Grid Editor values are mapped one-to-one to the block item data.

Migrating from Matryoshka

Matryoshka was an Umbraco package that added tab support for document types in Umbraco. The feature was subsequently added to the product itself.

We provide a migrator for this package in Umbraco.Deploy.Contrib.

This adds support for migrating Matryoshka Group Separators into native property groups. It removes the Matryoshka Data Types during import and migrates the document, media and member types. Native property groups are also changed into tabs, similarly to how they were displayed with Matryoshka installed.

To use, you register the migrators:

using Umbraco.Cms.Core.Composing;
using Umbraco.Deploy.Infrastructure.Migrators;

internal sealed class DeployMigratorsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DeployArtifactMigrators()
            .Append<ReplaceMatryoshkaArtifactMigrator>();
    }
}

Source Code Example - Nested Content to Block List

As described above, the nested content to block list migration will occur register the corresponding migrator with your application.

To help write your own migrations, we share the source code of an example that ships with Umbraco Deploy. This migration converts Nested Content to Block List.

First we have the artifact migrator that handles the conversion of the configuration stored with a datatype:

using System.Globalization;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;
using Umbraco.Deploy.Infrastructure.Migrators;

public class ReplaceNestedContentDataTypeArtifactMigrator : ReplaceDataTypeArtifactMigratorBase<NestedContentConfiguration, BlockListConfiguration>
{
    private readonly IContentTypeService _contentTypeService;

    public ReplaceNestedContentDataTypeArtifactMigrator(PropertyEditorCollection propertyEditors, IConfigurationEditorJsonSerializer configurationEditorJsonSerializer, IContentTypeService contentTypeService)
        : base(Constants.PropertyEditors.Aliases.NestedContent, Constants.PropertyEditors.Aliases.BlockList, propertyEditors, configurationEditorJsonSerializer)
        => _contentTypeService = contentTypeService;

    protected override BlockListConfiguration? MigrateConfiguration(NestedContentConfiguration configuration)
    {
        var blockListConfiguration = new BlockListConfiguration()
        {
            UseInlineEditingAsDefault = true // Similar to how Nested Content looks/works
        };

        if (configuration.MinItems > 0)
        {
            blockListConfiguration.ValidationLimit.Min = configuration.MinItems;
        }

        if (configuration.MaxItems > 0)
        {
            blockListConfiguration.ValidationLimit.Max = configuration.MaxItems;
        }

        if (configuration.ContentTypes is not null)
        {
            var blocks = new List<BlockListConfiguration.BlockConfiguration>();
            foreach (NestedContentConfiguration.ContentType nestedContentType in configuration.ContentTypes)
            {
                if (nestedContentType.Alias is not null &&
                    GetContentTypeKey(nestedContentType.Alias) is Guid contentTypeKey)
                {
                    blocks.Add(new BlockListConfiguration.BlockConfiguration()
                    {
                        Label = nestedContentType.Template,
                        ContentElementTypeKey = contentTypeKey
                    });
                }
            }

            blockListConfiguration.Blocks = blocks.ToArray();
        }

        if (blockListConfiguration.ValidationLimit.Min == 1 &&
            blockListConfiguration.ValidationLimit.Max == 1 &&
            blockListConfiguration.Blocks.Length == 1)
        {
            blockListConfiguration.UseSingleBlockMode = true;
        }

        return blockListConfiguration;
    }

    protected virtual Guid? GetContentTypeKey(string alias)
    {
        if (_contentTypeService.Get(alias) is IContentType contentTypeByAlias)
        {
            return contentTypeByAlias.Key;
        }

        // New content types are initially saved by Deploy with a custom postfix (to avoid duplicate aliases), so try to get the first matching item
        string aliasPrefix = alias + "__";
        foreach (IContentType contentType in _contentTypeService.GetAll())
        {
            if (contentType.Alias.StartsWith(aliasPrefix) &&
                int.TryParse(contentType.Alias[aliasPrefix.Length..], NumberStyles.HexNumber, null, out _))
            {
                return contentType.Key;
            }
        }

        return null;
    }
}

And secondly we have the property migrator that handles restructuring the content property data:

using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Deploy;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Models.Blocks;
using Umbraco.Cms.Core.Services;
using Umbraco.Deploy.Core;
using Umbraco.Deploy.Core.Migrators;
using Umbraco.Deploy.Infrastructure.Extensions;

public class NestedContentPropertyTypeMigrator : PropertyTypeMigratorBase
{
    private readonly ILogger<NestedContentPropertyTypeMigrator> _logger;
    private readonly IContentTypeService _contentTypeService;

    public NestedContentPropertyTypeMigrator(ILogger<NestedContentPropertyTypeMigrator> logger, IContentTypeService contentTypeService)
        : base(Constants.PropertyEditors.Aliases.NestedContent, Constants.PropertyEditors.Aliases.BlockList)
    {
        _logger = logger;
        _contentTypeService = contentTypeService;
    }

    public override object? Migrate(IPropertyType propertyType, object? value, IDictionary<string, string> propertyEditorAliases, IContextCache contextCache)
    {
        if (value is not string stringValue || !stringValue.TryParseJson(out NestedContentItem[]? nestedContentItems) || nestedContentItems is null)
        {
            if (value is not null)
            {
                _logger.LogWarning("Skipping migration of Nested Content items ({PropertyTypeAlias}), because value could not be parsed: {Value}.", propertyType.Alias, value);
            }

            return null;
        }

        var layoutItems = new List<BlockListLayoutItem>();
        var contentData = new List<BlockItemData>();

        foreach (NestedContentItem nestedContentItem in nestedContentItems)
        {
            IContentType? contentType = contextCache.GetContentTypeByAlias(_contentTypeService, nestedContentItem.ContentTypeAlias);
            if (contentType is null)
            {
                _logger.LogWarning("Skipping migration of Nested Content item ({Id}), because content type does not exist: {ContentTypeAlias}.", nestedContentItem.Id, nestedContentItem.ContentTypeAlias);
                continue;
            }

            var udi = new GuidUdi(Constants.UdiEntityType.Element, nestedContentItem.Id);

            layoutItems.Add(new BlockListLayoutItem()
            {
                ContentUdi = udi
            });

            contentData.Add(new BlockItemData()
            {
                Udi = udi,
                ContentTypeKey = contentType.Key,
                RawPropertyValues = nestedContentItem.RawPropertyValues
            });
        }

        var blockValue = new BlockValue()
        {
            Layout = new Dictionary<string, JToken>()
            {
                { Constants.PropertyEditors.Aliases.BlockList, JToken.FromObject(layoutItems) }
            },
            ContentData = contentData
        };

        return JsonConvert.SerializeObject(blockValue, Formatting.None);
    }

    internal class NestedContentItem
    {
        [JsonProperty("key")]
        public Guid Id { get; set; } = Guid.NewGuid(); // Ensure a unique key is set, even if the JSON doesn't have one

        [JsonProperty("name")]
        public string? Name { get; set; }

        [JsonIgnore]
        public object? PropType { get; set; } // Ensure this property is ignored

        [JsonProperty("ncContentTypeAlias")]
        public string ContentTypeAlias { get; set; } = null!;

        [JsonExtensionData]
        public Dictionary<string, object?> RawPropertyValues { get; set; } = null!;
    }
}

What is import and export?

The import and export feature of Umbraco Deploy allows you to transfer content and schema between Umbraco environments. Exports are made from one environment to a .zip file. And this file is imported into another environment to update the Umbraco data there.

When to use import and export

Umbraco Deploy provides two primary workflows for managing different types of Umbraco data:

• Umbraco schema (such as document types and data types) are transferred as .uda files serialized to disk. They are deployed to refresh the schema information in a destination environment along with code and template updates.

• Umbraco content (such as content and media) are transferred by editors using backoffice operations.

We recommend using these approaches for day-to-day editorial and developer activities.

Import and export is intended more for larger transfer options, project upgrades, or one-off tasks when setting up new environments.

As import and export is a two-step process, it doesn't require inter-environment communication. This allows us to process much larger batches of information without running into hard limits imposed by Cloud hosting platforms.

We are also able provide hooks to allow for migrations of artifacts (such as data types) and property data when importing. This should allow you to migrate your Umbraco data from one Umbraco major version to a newer one.

Exporting content and schema

To export content and schema, you can select either a specific item of content, or a whole tree or workspace.

When exporting, you can choose to include associated media files. Bear in mind that including media files for a large site can lead to a big zip file. So even with this option, you might want to consider a different method for transferring large amounts of media. For example using direct transfer between Cloud storage accounts or File Transfer Protocol (FTP).

If your account has access to the Settings section, you can also choose to include the schema information and related files as well.

Umbraco Deploy will then serialize all the selected items to individual files, archive them into a zip file and make that available for download. You can download the file using the Download button.

After the download, you should also delete the archive file from the server. You can do this immediately via the Delete button available in the dialog.

If you miss doing this, you can also clean up archive files from the Umbraco Deploy dashboard in the Settings section.

Importing content and schema

Having previously exported content and schema to a zip file, you can import this into a new environment.

You can upload the file via the browser.

Similar to when exporting, you can choose to import everything from the archive file, or only content, schema or files.

We validate the file before importing. Schema items that content depends on must either be in the upload itself or already exist on the target environment with the same details. If there are any issues that mean the import cannot proceed, it will be reported. You may also be given warnings for review. You can choose to ignore these and proceed if they aren't relevant to the action you are carrying out.

The import then proceeds, processing all the items provided in the zip file.

Once complete or on close of the dialog, the imported file will be deleted from the server. If this is missed, perhaps via a closed browser, you can also delete archive files from the Umbraco Deploy dashboard in the Settings section.

Migrating whilst importing

It is possible to migrate schema and content whilst importing. For example, to change Data Type using Nested Content to Block List and ensure content data is imported to the correct Block Editor format.

Deploy contains base classes and implementations to handle common migrations that need to be registered in code, as explained in Import with migrations.

Migrating from Umbraco 7

The import and export feature is not available in Deploy 2 for Umbraco 7. We have though released a package to allow creating an export. This needs to be done in code and requires additional legacy migrators to be able to import into a newer version. This is explained in Migrating from Umbraco 7.

Service details (programmatically importing and exporting)

Underlying the functionality of import/export with Deploy is the import/export service, defined by the IArtifactImportExportService.

You may have need to make use of this service directly if building something custom with the feature. For example you might want to import from or export to some custom storage.

The service interface defines two methods:

• ExportArtifactsAsync - takes a collection of artifacts and a storage provider defined by the IArtifactExportProvider interface. The artifacts are serialized and exported to storage.

  • IArtifactExportProvider defines methods for creating streams for writing serialized artifacts or files handled by Deploy (media, templates, stylesheets etc.).

• ImportArtifactsAsync - takes storage provider containing an import defined by the IArtifactImportProvider interface. The artifacts from storage are imported into Umbraco.

  • IArtifactImportProvider defines methods for creating streams for reading serialized artifacts or files handled by Deploy (media, templates, stylesheets etc.).

Implementations for IArtifactExportProvider and IArtifactImportProvider are provided for:

• A physical directory.

• An Umbraco file system.

• A zip file.

These are all accessible for use via extension methods available on IArtifactImportExportService found in the Umbraco.Deploy.Infrastructure.Extensions namespace.

The following example shows this service in use, importing and exporting from a zip file on startup:

using System.IO.Compression;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Deploy;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Extensions;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Deploy.Core;
using Umbraco.Deploy.Core.Connectors.ServiceConnectors;
using Umbraco.Deploy.Infrastructure;
using Umbraco.Deploy.Infrastructure.Extensions;
​
internal class ArtifactImportExportComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.AddNotificationAsyncHandler<UmbracoApplicationStartedNotification, ArtifactImportExportStartedAsyncHandler>();
​
    private sealed class ArtifactImportExportStartedAsyncHandler : INotificationAsyncHandler<UmbracoApplicationStartedNotification>
    {
        private readonly IHostEnvironment _hostEnvironment;
        private readonly IArtifactImportExportService _diskImportExportService;
        private readonly IServiceConnectorFactory _serviceConnectorFactory;
        private readonly IFileTypeCollection _fileTypeCollection;
​
        public ArtifactImportExportStartedAsyncHandler(IHostEnvironment hostEnvironment, IArtifactImportExportService diskImportExportService, IServiceConnectorFactory serviceConnectorFactory, IFileTypeCollection fileTypeCollection)
        {
            _hostEnvironment = hostEnvironment;
            _diskImportExportService = diskImportExportService;
            _serviceConnectorFactory = serviceConnectorFactory;
            _fileTypeCollection = fileTypeCollection;
        }
​
        public async Task HandleAsync(UmbracoApplicationStartedNotification notification, CancellationToken cancellationToken)
        {
            var deployPath = _hostEnvironment.MapPathContentRoot(Constants.SystemDirectories.Data + "/Deploy");
            await ImportAsync(Path.Combine(deployPath, "import.zip"));
​
            Directory.CreateDirectory(deployPath);
            await ExportAsync(Path.Combine(deployPath, $"export-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}.zip"));
        }
​
        private async Task ImportAsync(string zipFilePath)
        {
            if (File.Exists(zipFilePath))
            {
                using ZipArchive zipArchive = ZipFile.OpenRead(zipFilePath);
                await _diskImportExportService.ImportArtifactsAsync(zipArchive);
            }
        }
​
        private async Task ExportAsync(string zipFilePath)
        {
            using ZipArchive zipArchive = ZipFile.Open(zipFilePath, ZipArchiveMode.Create);
​
            IEnumerable<Udi> udis = DeployEntityTypes.GetEntityTypes(_fileTypeCollection, DeployEntityTypeCategories.ContentAndSchema).Select(Udi.Create);
            var contextCache = new DictionaryCache();
            string[] dependencyEntityTypes = DeployEntityTypes.GetEntityTypes(_fileTypeCollection, DeployEntityTypeCategories.All);
​
            await _diskImportExportService.ExportArtifactsAsync(_serviceConnectorFactory, udis, Constants.DeploySelector.ThisAndDescendants, contextCache, zipArchive, dependencyEntityTypes: dependencyEntityTypes);
        }
    }
}