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

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.

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.

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

• was changed from a list to a dictionary.

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

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.

Setting up CI/CD pipeline with Github Actions

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

Setting up CI/CD pipeline with Azure DevOps

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

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

trigger:
- main

pool:
  vmImage: 'windows-latest'

variables:
  solution: '**/*.sln'
  buildPlatform: 'Any CPU'
  buildConfiguration: 'Release'

  vsSolutionName: DeployOnPremSite
  vsProjectName: DeployOnPremSite
  umbracoDeployTriggerDeploy: $(Build.SourcesDirectory)\$(vsSolutionName)\$(vsProjectName)\TriggerDeploy.ps1
  umbracoDeployReason: AzureDeployment

  deployApiSecret: <set in Azure Pipeline secret>
  azureSubscription: <set in Azure Pipeline variable>
  webAppName: <set in Azure Pipeline variable>
  resourceGroupName: <set in Azure Pipeline variable>
  deploySlotName: <set in Azure Pipeline variable>
  deployBaseUrl: <set in Azure Pipeline variable>

steps:
#1 NuGet Tool Install
- task: NuGetToolInstaller@1
  displayName: Install NuGet

#2 NuGet Restore
- task: NuGetCommand@2
  displayName: Restore NuGet packages
  inputs:
    restoreSolution: '$(solution)'

#3 Build the VS Solution and publish the output to a zip file
- task: VSBuild@1
  displayName: Build solution
  inputs:
    solution: '$(solution)'
    msbuildArgs: '/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:DesktopBuildPackageLocation="$(build.artifactStagingDirectory)\WebApp.zip" /p:DeployIisAppPath="Default Web Site"'
    platform: '$(buildPlatform)'
    configuration: '$(buildConfiguration)'

#4 Deploy to an Azure web app slot
- task: AzureRmWebAppDeployment@4
  displayName: Deploy to web app
  inputs:
    ConnectionType: 'AzureRM'
    azureSubscription: '$(azureSubscription)'
    appType: 'webApp'
    WebAppName: '$(webAppName)'
    deployToSlotOrASE: true
    ResourceGroupName: '$(resourceGroupName)'
    SlotName: '$(deploySlotName)'
    packageForLinux: '$(build.artifactStagingDirectory)\WebApp.zip'

#5 Trigger the Umbraco Deploy extraction
- task: PowerShell@2
  displayName: Run PowerShell script
  inputs:
    filePath: '$(umbracoDeployTriggerDeploy)'
    arguments: '-InformationAction:Continue -Action TriggerWithStatus -ApiSecret $(deployApiSecret) -BaseUrl $(deployBaseUrl) -Reason $(umbracoDeployReason) -Verbose'

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.

Quick start (new sites)

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

1. Set up Git repository and new Umbraco project

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

2. Install Umbraco Deploy via NuGet

   • Umbraco Deploy can be installed via NuGet.

3. Configure CI/CD build server

   • 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

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 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 .

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):

• Run a git pull origin <branchname>.

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

Once all code and meta data is in sync between your environments, it's time to transfer your content and media. This is done from the Umbraco Backoffice.

Content and media transfers are flexible which means you have complete control over which content nodes and/or media items you want to transfer. You can transfer it all in one go, a few at a time or transfer only a single node.

Transferring content will overwrite any existing nodes on the target environment - content transfers will transfer the items that you select in the "source" environment to the "target" environment exactly the same as it was in the "source". This means that if you have some content on the target environment already, this will be replaced by the new content from the source environment.

Important: Content and Media transfers will only work if you've deployed all changes to your meta data before hand. Please refer to our documentation on how to deploy meta data from .

Step-by-step

Let’s go through a content transfer step by step. Imagine you’ve finished working on new content for your project locally and you are ready to transfer the changes to your development site.

You want to transfer the whole site. You start from the Home node and choose to transfer everything under it:

1. Click on the ellipsis next to the Home node in the Content tree.

2. Choose "Do something else".

3. There you get the choice of Queue for transfer.

   • If you’re currently editing the Home page you could also use the Actions dropdown to find Queue for transfer.

4. Choose if you want to include all pages under the chosen page or only transfer the chosen node.

   • If you wish to transfer all your content at once, right-click the top of the Content tree where you will also find Queue for transfer - this will queue all your content for transfer.

5. Select the language versions that you want to queue for transfer. Only languages for which you have permission to access will be selectable.

6. Set the publish date and time if you want to change when the transferred content should be published.

   By default, the content will be transferred in its current published state. So if the content is published in the current environment, the changes will be deployed and the item immediately be published in the destination. If you prefer to schedule the publishing of the changes, you can do so by selecting a publish date.

7. Click Queue to add the content item to the transfer queue.
8. Go to the Deployment dashboard by clicking on the Content section header.

   • You will be able to see which items are currently ready to be transferred - this will include both content and media that you've queued for transfer.

9. Confirm by clicking Transfer toDevelopment and monitor the progress of the transfer.

If everything went well, you will see the confirmation screen saying that the transfer has succeeded.

Media items

Media items are transferred the same way as content:

1. In the Media section Right-click the items you want to transfer and choose Queue for transfer.

   • Or right-click the top of the Media section to transfer all you media at once.

2. Go to the Deployment dashboard in the Content section to see the items you've queued for transfer and to transfer your items.

Umbraco Forms

Once the setting have been added to the source and target environment forms can be transferred the same way as content and media:

1. In the Forms section Right-click the items you want to transfer and choose Queue for transfer.

   • Or right-click the top of the Forms section to transfer all your Forms at once.

2. Go to the Deployment dashboard in the Content section to see the items you've queued for transfer and to transfer your items.

Schema Mismatches

Sometimes a content transfer might not be possible. For example if you add a new property to the HomePage Document type and you don’t have that property in both environments, you’ll get an error with a hint on how to fix this.

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 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.

Review timeouts

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

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"

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.

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.

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.

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.

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.

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!;
    }
}

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.

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.

Umbraco Deploy supports the deployment of CMS schema information and definitions from the HQ's Forms package, along with managed content and media. Additionally, it can be extended by package or custom solution developers. This allows the deployment of custom data, such as that stored in your own database tables.

As a package or solution developer, you can hook into the disk-based serialization and deployment. It is similar to that used for Umbraco Document Types and Data Types. It's also possible to provide the ability for editors to deploy custom data via the Backoffice. In the same way that Umbraco content and media can be queued for transfer and restored.

Concepts and Examples

Entities

Entities are what you may be looking to transfer between two websites using Deploy. Within Umbraco, they are the Document Types, Data Type, documents etc. In a custom solution or a package, there may be representations of some other data that's being stored separately from Umbraco content. These can still be managed in the Backoffice using custom trees and editors.

For the purposes of subsequent code samples, we'll consider an example entity as a Plain Old Class Object (POCO) with a few properties.

public class Example
{
    public Guid Id { get; set; }

    public string Name { get; set; }

    public string Description { get; set; }
}

Artifacts

Every entity Deploy works with, whether from Umbraco core or custom data, needs to have an artifact representation. You can consider an artifact as a container capable of knowing everything there is to know about a particular entity is defined. They are used as a transport object for communicating between Deploy environments.

They can also be serialized to JSON representations. These are visible in the .uda files seen on disk in the /data/revisions/ folder for schema transfers. It is also used when transferring content between different environments over HTTP requests.

Artifact classes must inherit from DeployArtifactBase.

The following example shows an artifact representing the entity and it's single property for transfer:

public class ExampleArtifact : DeployArtifactBase<GuidUdi>
{
    public ExampleArtifact(GuidUdi udi, IEnumerable<ArtifactDependency> dependencies = null)
        : base(udi, dependencies)
    { }

    public string Description { get; set; }
}

Control Over Serialization

In most cases the default settings Umbraco Deploy uses for serialization will be appropriate. For example, it ensures that culture specific values such as dates and decimal numbers are rendered using an invariant culture. This ensures that any differences in regional settings between source and destination servers are not a concern.

If you do need more control, attributes can be applied to the artifact properties.

For example, to ensure a decimal value is serialized to a consistent number of decimal places you can use the following. RoundingDecimalJsonConverter is found in the Umbraco.Deploy.Serialization namespace

[JsonConverter(typeof(RoundingDecimalJsonConverter), 2)]
public decimal Amount { get; set; }

Service Connectors

Service connectors are responsible for knowing how to handle the mapping between artifacts and entities. They know how to gather all the data required for the type of entity they correspond to, including figuring out what dependencies are needed. For example, in Umbraco, how a Document Type depends on a Data Type. They are responsible for packaging an entity as an artifact and for extracting an entity from an artifact and persisting it in a destination site.

Service connectors inherit from ServiceConnectorBase and are constructed with the artifact and entity as generic type arguments.

The class is decorated with a UdiDefinition via which the name of the entity type is provided. This needs to be unique across all entities so it's likely worth prefixing with something specific to your package or application.

The following example shows a service connector, responsible for handling the artifact shown above and it's related entity. There are no dependencies to consider here. More complex examples involve collating the dependencies and potentially handling extraction in more than one pass to ensure updates are made in the correct order.

An illustrative data service is provided via dependency injection. This will be whatever is appropriate for to use for Create, Read, Update and Delete (CRUD) operations around reading and writing of entities.

[UdiDefinition("mypackage-example", UdiType.GuidUdi)]
public class ExampleServiceConnector : ServiceConnectorBase<ExampleArtifact, GuidUdi, ArtifactDeployState<ExampleArtifact, Example>>
{
    private readonly IExampleDataService _exampleDataService;

    public ExampleServiceConnector(IExampleDataService exampleDataService) => _exampleDataService = exampleDataService;

    public override ExampleArtifact GetArtifact(object o)
    {
        var entity = o as Example;
        if (entity == null)
        {
            throw new InvalidEntityTypeException($"Unexpected entity type \"{o.GetType().FullName}\".");
        }

        return GetArtifact(entity.GetUdi(), entity);
    }

    public override ExampleArtifact GetArtifact(GuidUdi udi)
    {
        EnsureType(udi);
        var entity = _exampleDataService.GetExampleById(udi.Guid);

        return GetArtifact(udi, entity);
    }

    private ExampleArtifact GetArtifact(GuidUdi udi, Example entity)
    {
        if (entity == null)
        {
            return null;
        }

        var dependencies = new ArtifactDependencyCollection();
        var artifact = Map(udi, entity, dependencies);
        artifact.Dependencies = dependencies;

        return artifact;
    }

    private ExampleArtifact Map(GuidUdi udi, Example entity, ICollection<ArtifactDependency> dependencies)
    {
        var artifact = new ExampleArtifact(udi);
        artifact.Description = example.Description;
        return artifact;
    }

    private string[] ValidOpenSelectors => new[]
    {
        DeploySelector.This,
        DeploySelector.ThisAndDescendants,
        DeploySelector.DescendantsOfThis
    };
    private const string OpenUdiName = "All Examples";

    public override void Explode(UdiRange range, List<Udi> udis)
    {
        EnsureType(range.Udi);

        if (range.Udi.IsRoot)
        {
            EnsureSelector(range, ValidOpenSelectors);
            udis.AddRange(_exampleDataService.GetExamples().Select(e => e.GetUdi()));
        }
        else
        {
            var entity = _exampleDataService.GetExampleById(((GuidUdi)range.Udi).Guid);
            if (entity == null)
            {
                return;
            }

            EnsureSelector(range.Selector, DeploySelector.This);
            udis.Add(entity.GetUdi());
        }
    }

    public override NamedUdiRange GetRange(string entityType, string sid, string selector)
    {
        if (sid == "-1")
        {
            EnsureSelector(selector, ValidOpenSelectors);
            return new NamedUdiRange(Udi.Create("mypackage-example"), OpenUdiName, selector);
        }

        if (!Guid.TryParse(sid, out Guid id))
        {
            throw new ArgumentException("Invalid identifier.", nameof(sid));
        }

        var entity = _exampleDataService.GetExampleById(id);
        if (entity == null)
        {
            throw new ArgumentException("Could not find an entity with the specified identifier.", nameof(sid));
        }

        return GetRange(entity, selector);
    }

    public override NamedUdiRange GetRange(GuidUdi udi, string selector)
    {
        EnsureType(udi);

        if (udi.IsRoot)
        {
            EnsureSelector(selector, ValidOpenSelectors);
            return new NamedUdiRange(udi, OpenUdiName, selector);
        }

        var entity = _exampleDataService.GetExampleById(udi.Guid);
        if (entity == null)
        {
            throw new ArgumentException("Could not find an entity with the specified identifier.", nameof(udi));
        }

        return GetRange(entity, selector);
    }

    private static NamedUdiRange GetRange(Example e, string selector) => new NamedUdiRange(e.GetUdi(), e.Name, selector);

    public override ArtifactDeployState<ExampleArtifact, Example> ProcessInit(ExampleArtifact art, IDeployContext context)
    {
        EnsureType(art.Udi);

        var entity = _exampleDataService.GetExampleById(art.Udi.Guid);

        return ArtifactDeployState.Create(art, entity, this, 1);
    }

    public override void Process(ArtifactDeployState<ExampleArtifact, Example> state, IDeployContext context, int pass)
    {
        switch (pass)
        {
            case 1:
                Pass1(state, context);
                state.NextPass = 2;
                break;
            default:
                state.NextPass = -1; // exit
                break;
        }
    }

    private void Pass1(ArtifactDeployState<ExampleArtifact, Example> state, IDeployContext context)
    {
        var artifact = state.Artifact;

        artifact.Udi.EnsureType("mypackage-example");

        var isNew = state.Entity == null;

        var entity = state.Entity ?? new Example { Id = artifact.Udi.Guid };

        entity.Name = artifact.Name;
        entity.Description = artifact.Description;

        if (isNew)
        {
            _exampleDataService.AddExample(entity);
        }
        else
        {
            _exampleDataService.UpdateExample(entity);
        }
    }
}

It's also necessary to provide an extension method to generate the appropriate identifier:

public static GuidUdi GetUdi(this Example entity)
{
    if (entity == null) throw new ArgumentNullException("entity");
    return new GuidUdi("mypackage-example", entity.Id).EnsureClosed();
}

Handling Dependencies

Umbraco entities often have dependencies on one another, this may also be the case for any custom data you are looking to deploy. If so, you can add the necessary logic to your service connector to ensure dependencies are added. This will ensure Umbraco Deploy also ensures the appropriate dependencies are in place before initiating a transfer.

If the dependent entity is also deployable, it will be included in the transfer. Or if not, the deployment will be blocked and the reason presented to the user.

In the following illustrative example, if deploying a representation of a "Person", we ensure their "Department" dependency is added. This will indicate that it must exist to allow the transfer. We can also use ArtifactDependencyMode.Match to ensure the dependent entity not only exists but also matches in all properties.

private PersonArtifact Map(GuidUdi udi, Person person, ICollection<ArtifactDependency> dependencies)
{
    var artifact = new PersonArtifact(udi)
    {
        Alias = person.Name,
        Name = person.Name,
        DepartmentId = person.Department.Id,
    };

    // Department node must exist to deploy the person.
    dependencies.Add(new ArtifactDependency(person.Department.GetUdi(), true, ArtifactDependencyMode.Exist));

    return artifact;
}

Value Connectors

As well as dependencies at the level of entities, we can also have dependencies in the property values as well. In Umbraco, an example of this is the multi-node tree picker property editor. It contains references to other content items, that should also be deployed along with the content that hosts the property itself.

Value connectors are used to track these dependencies and can also be used to transform property data as it is moved between environments.

The following illustrative example considers a property editor that stores the integer ID of an media item. The integer ID of a media item is not consistent between environments, so we'll need to transform it. And we also want to ensure that the related media item itself is transferred as well as the integer ID reference.

using Umbraco.Cms.Core.Deploy;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core;
using Microsoft.Extensions.Logging;
using Umbraco.Deploy.Core.Connectors.ValueConnectors;

namespace MyExtensions;

public class MyMediaPropertyValueConnector : ValueConnectorBase
{
    private readonly IEntityService _entityService;
    private readonly ILogger<MyMediaPropertyValueConnector> _logger;

    public MyMediaPropertyValueConnector(IEntityService entityService, ILogger<MyMediaPropertyValueConnector> logger)
    {
        _entityService = entityService;
        _logger = logger;
    }

    public override IEnumerable<string> PropertyEditorAliases => new[] { "MyMediaPropertyEditor" };

    public override string? ToArtifact(object? value, IPropertyType propertyType, ICollection<ArtifactDependency> dependencies, IContextCache contextCache)
    {
        var svalue = value as string;
        if (string.IsNullOrWhiteSpace(svalue))
        {
            return null;
        }

        if (!int.TryParse(svalue, out var intvalue))
        {
            return null;
        }

        Attempt<Guid> getKeyAttempt = _entityService.GetKey(intvalue, UmbracoObjectTypes.Media);

        if (getKeyAttempt.Success)
        {
            var udi = new GuidUdi(Constants.UdiEntityType.Media, getKeyAttempt.Result);
            dependencies.Add(new ArtifactDependency(udi, false, ArtifactDependencyMode.Exist));

            return udi.ToString();
        }
        else
        {
            _logger.LogDebug($"Couldn't convert integer value #{intvalue} to UDI");
        }

        return null;
    }

    public override object? FromArtifact(string? value, IPropertyType propertyType, object? currentValue, IContextCache contextCache)
    {
        if (string.IsNullOrWhiteSpace(value))
        {
            return null;
        }

        if (!UdiParser.TryParse(value, out GuidUdi? udi) || udi!.Guid == Guid.Empty)
        {
            return null;
        }

        Attempt<int> getIdAttempt = _entityService.GetId(udi.Guid, UmbracoObjectTypes.Media);

        if (!getIdAttempt.Success)
        {
            return null;
        }

        return getIdAttempt.Result.ToString();
    }
}

Grid Cell Value Connector

The third and final type of connector is the grid cell value connector. These are responsible for converting values and tracking dependencies for grid editors.

Umbraco Deploy comes with connectors for the built-in editors such as for media and macros.

It's also possible to create your own, as in this example.

The following grid editor is an illustrative example for a rudimentary custom image picker. It contains a package mamifest file:

{
    "gridEditors": [
        {
            "name": "TestImagePicker",
            "alias": "testImagePicker",
            "view": "/App_Plugins/TestGridEditor/editor.html",
            "icon": "icon-code"
        }
    ]
}

And an editor view:

<div>
    <label>Enter The Integer Id Of An Image:</label>
    <input ng-model="control.value" type="number">
</div>

The value stored by the grid editor will be the integer Id of a media item.

When transferring this value to an upstream environment using Umbraco Deploy, these tasks are required:

• The integer Id needs to be converted to a Guid for transfer. Guids for content and media are the same across environments but integer Ids will differ.

• On creation in the upstream environment, the Guid value needs to be converted back to an integer for storage in the grid editor.

• A dependency on the selected media item needs to be tracked, such that it will be transferred to the upstream environment along with the changes to the grid content.

We can implement that via a grid cell value connector. The following code is for Umbraco Deploy 10.1. For earlier versions, or from Umbraco Deploy 11, the base class should be GridCellValueConnectorBase.

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Deploy;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Services;
using Umbraco.Deploy.Core;

namespace Umbraco.Deploy.Infrastructure.Connectors.GridCellValueConnectors
{
    public class CustomMediaGridCellValueConnector : GridCellValueConnectorBase2
    {
        public CustomMediaGridCellValueConnector(IEntityService entityService, ILocalLinkParser localLinkParser)
            : base(entityService, localLinkParser)
        {
        }

        public override bool IsConnector(string view) => string.Equals(view, "/App_Plugins/TestGridEditor/editor.html", StringComparison.OrdinalIgnoreCase);
        public override string? GetValue(GridValue.GridControl control, ICollection<ArtifactDependency> dependencies, IContextCache contextCache)
        {
            var value = control.Value?.ToString();
            if (string.IsNullOrEmpty(value))
            {
                return null;
            }

            if (!int.TryParse(value, out var valueAsInt))
            {
                return null;
            }

            Udi? mediaUdi = GetUdi(valueAsInt, UmbracoObjectTypes.Media);
            if (mediaUdi == null)
            {
                return null;
            }
            dependencies.Add(new ArtifactDependency(mediaUdi, false, ArtifactDependencyMode.Exist));
            return mediaUdi.ToString();
        }
        public override void SetValue(GridValue.GridControl control, IContextCache contextCache)
        {
            var value = control.Value?.ToString();
            if (string.IsNullOrWhiteSpace(value))
            {
                return;
            }

            var guidUdi = UdiParser.Parse(value.ToString() ?? string.Empty) as GuidUdi;
            if (guidUdi == null)
            {
                return;
            }

            var mediaId = GetNodeId(guidUdi);
            if (!mediaId.HasValue)
            {
                return;
            }

            control.Value = mediaId.Value;
        }
    }
}