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 15 including all changes for this version.

15.0.0 (November 14th 2024)

• Update CMS dependency to 15.0.0

15.0.0-rc4 (November 13th 2024)

• Update CMS dependency to 15.0.0-rc4

• Preview of features and bug fixes due in 13.3 and 14.2:

  • Import on startup

  • Added ValidateDependenciesOnImport setting to disable dependency validation on import

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

15.0.0-rc3 (November 7th 2024)

• Update CMS dependency to 15.0.0-rc3

15.0.0-rc2 (October 24th 2024)

• Update CMS dependency to 15.0.0-rc2

• Preview of features and bug fixes due in 13.3 and 14.2:

  • Add option to include all schema in a workspace export

  • Add option to export from transfer queue

  • Fix BlockValue obsoleted properties (set GUID keys instead of UDIs and support block level variants)

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

• Restructure keys and add new UI localizations

15.0.0-rc1 (October 11th 2024)

• Compatibility with Umbraco 15

  • See full details of breaking changes under the Version-specific Upgrade Guide

• Removed AcceptInvalidCertificates setting (configure DeployHttpClient typed client instead)

• Removed RemoteTreeNode model (use RemoteTreeEntity instead) and TryParseEntityIdFromNodeIdDelegate (use TryParseUdiRangeFromNodeIdDelegate instead) in DeployTransferRegisteredEntityTypeDetail

• Added MigrateAsync(...) method to IPropertyTypeMigrator and updated PropertyTypeMigratorBase and implementations to use async instead

Deploy Contrib

15.0.0 (November 14th 2024)

• Update CMS and Deploy dependencies to 15.0.0

15.0.0-rc4 (November 13th 2024)

• Update CMS and Deploy dependencies to 15.0.0-rc4

15.0.0-rc3 (November 7th 2024)

• Update CMS and Deploy dependencies to 15.0.0-rc3

15.0.0-rc2 (October 24th 2024)

• Update CMS and Deploy dependencies to 15.0.0-rc2

15.0.0-rc1 (October 14th 2024)

• Compatibility with Umbraco 15 and Deploy 15

• Removed obsolete (and unused) legacy PrevaluePropertyValueArtifactMigratorBase, CheckBoxListPropertyValueArtifactMigrator DropDownListFlexiblePropertyValueArtifactMigrator and RadioButtonListPropertyValueArtifactMigrator migrators, as they are replaced with PrevalueArtifactMigrator and property type migrators that support nested/recursive properties (see PR #71)

• Removed MediaPickerDataTypeArtifactMigrator, as it is replaced with ReplaceMediaPickerDataTypeArtifactMigrator and DefaultLegacyDataTypeConfigurationArtifactMigrator

• Removed MultiNodeTreePickerDataTypeArtifactMigrator, as it is replaced with DefaultLegacyDataTypeConfigurationArtifactMigrator

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

This article provides specific upgrade documentation for migrating to Umbraco Deploy version 15.

Version Specific Upgrade Notes History

Version 15 of Umbraco Deploy has a minimum dependency on Umbraco CMS core of 15.0.0. It runs on .NET 9.

Breaking changes

Version 15 contains breaking changes. The breaking changes appear in areas related to extending Deploy to support additional entities and property editors. For reference though, the full details are listed here:

Async methods

Asynchronous methods have been added to the following interfaces:

• IPropertyTypeMigrator:

  • MigrateAsync(...)

These methods all have a default implementation that forwards the calls to the synchronous methods (to maintain backwards compatibility). The synchronous methods have been obsoleted and Deploy will now always call the new asynchronous methods. Implementations should be updated to start using those instead.

• PropertyTypeMigratorBase and GridPropertyTypeMigratorBase: the synchronous Migrate(...) method is obsoleted and causes a compiler error when directly invoked (to avoid potential deadlocks, because it forwards to the asynchronous method using GetAwaiter().GetResult());

• All property type migrator implementations inheriting from the above base classes have been updated to use the asynchronous methods as well.

Removed AcceptInvalidCertificates setting

The AcceptInvalidCertificates setting previously configured the ServicePointManager to accept all certificates. However, this class is obsoleted in .NET 9 and no longer affects HttpClient.

Deploy uses a type of client to make HTTP requests between environments and this client can be configured to accept any certificate:

builder.Services.AddHttpClient<DeployHttpClient>().ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
{
  // Only use this for testing purposes or if you have other security in place (e.g. only allow environments to connect over an internal network)
  ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
});

Dependencies

• Umbraco CMS dependency was updated to 15.0.0.

Legacy version-specific upgrade notes

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

Umbraco Deploy is a commercial product. You will need a valid license to use the product.

A license for Umbraco Deploy is included when hosting on Umbraco Cloud.

How does it work?

Licenses are sold per domain and will also work on all subdomains. With every license, you will also be able to configure two development/testing domains.

Example

Let's say that you have a license configured for your domain, mysite.com, and you've configured two development domains, devdomain.com and devdomain2.com.

The license will cover the following domains:

• localhost

• *.mysite.com

• www.mysite.com

• mysite.com.local

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

There are a few differences as to what the licenses cover:

A single license covers one Umbraco solution. It includes all domains hosted by the solution, all production environments (if load-balancing), and all non-production environments.

To clarify the above:

• You only need one license when you have a solution covering multiple domains- for example, www.mysite.com and www.mysite.dk - load balanced in production over multiple servers running from the same database, managed from the same backoffice instance, and with any number of non-production environments (staging, QA, etc.)

• You need two licenses if you have a web presence that consists of two separate websites hosted on different domains or sub-domains - for example, www.mysite.com and shop.mysite.com - with each of these managed as a separate Umbraco installation using their own database and backoffice in production.

Purchasing your license

You can look at the pricing, plans, features, and purchase the license on the Umbraco Deploy On-premises page.

Installing your license

Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.

For Umbraco Deploy On-Premise 12 and above, 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": {
    "CMS": {
      ...
    },
    "Licenses": {
      "Products": {
        "Umbraco.Deploy.OnPrem": "<your license key>"
      }
    },
    "Deploy": {
       ...
    }

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

Validating the license

On start-up and on a schedule, Umbraco running Deploy On-premise will call out to a service. It will pass the configured license key to determine its validity. The response triggers a notification that the Umbraco Deploy will handle. It will amend the available functionality as appropriate to a valid, invalid or expired license.

You can view the status of the Umbraco Deploy On-premise license in the backoffice. This is available via the Settings section, listed along with any other products using the same licensing service:

When and how to configure an UmbracoApplicationUrl

The website domain used for validating the license is determined from your Umbraco instance. To ensure the correct one is used, you can configure the UmbracoApplicationUrl.

If you are running on a single domain for both your frontend and backend environments, it's not necessary to configure a UmbracoApplicationUrl.

If you have different domains for your frontend and backend, then it's advised that you configure an UmbracoApplicationUrl set to your backoffice URL. This helps the licensing engine know which URL should be used for validation checks. Without this configuration setting, the licensing engine will try and work out the domain to validate from the HTTP request object. This can lead to errors when switching between domains.

An UmbracoApplicationUrl can be configured in your appSettings.json file like so:

{
    "Umbraco": {
        "CMS": {
            "WebRouting": {
                "UmbracoApplicationUrl": "https://admin.my-custom-domain.com/"
            }
        }
    }
}

See the Fixed Application URL documentation for more details about this setting.

Validating a license without an outgoing Internet connection

Some Umbraco installations will have a highly locked down production environment, with firewall rules that prevent outgoing HTTP requests. This will interfere with the normal process of license validation.

On start-up, and periodically whilst Umbraco is running, the license component used by Umbraco Deploy will make an HTTP POST request to https://license-validation.umbraco.com/api/ValidateLicense.

If it's possible to do so, the firewall rules should be adjusted to allow this request.

If such a change is not feasible, there is another approach you can use.

You will need to have a server, or serverless function, that is running and can make a request to the online license validation service. That needs to run on a daily schedule, making a request and relaying it onto the restricted Umbraco environment.

To set this up, firstly ensure you have a reference to Umbraco.Licenses version 13.1 or higher. This will be the case if you are running Umbraco Deploy 13.1 or higher. If you are on an earlier version, you can add a direct package reference for Umbraco.Licenses.

Then configure a random string as an authorization key in configuration. This is used as protection to ensure only valid requests are handled. You can also disable the normal regular license checks - as there is no point in these running if they will be blocked:

  "Umbraco": {
    "Licenses": {
      "Products": {
        "Umbraco.Deploy.OnPrem": "<your license key>"
      }
    },
    "LicensesOptions": {
      "EnableScheduledValidation": false,
      "ValidatedLicenseRelayAuthKey": "<your authorization key>"
    }

Your Internet enabled server should make a request of the following form to the online license validation service:

POST https://license-validation.umbraco.com/api/ValidateLicense
{
    "ProductId": "Umbraco.Deploy.OnPrem",
    "LicenseKey": "<your license key>",
    "Domain": "<your licensed domain>"
}

The response should be relayed exactly via an HTTP request to your restricted Umbraco environment:

POST http://<your umbraco environment>/umbraco/licenses/validatedLicense/relay?productId=<product id>&licenseKey=<license key>

A header with a key of X-AUTH-KEY and value of the authorization key you have configured should be provided.

This will trigger the same processes that occur when the normal scheduled validation completes ensuring your product is considered licensed.

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.

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 our.umbraco.com.

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.

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.

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

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.

The following steps will take you through setting up a build server in Azure Web Apps. Go to the Azure portal and find the empty website that we have set up and want to connect to.

1. Go to the Deployment Center.

In the Deployment Center we can set up the CI/CD build server. With this example we are going to set up our build server by using Github Actions. It is possible to set up the build server however you want as long as it supports executing powershell scripts.

1. Go to the Settings tab.

2. Choose which source and build provider to use.

   • In this case we want to choose Github.

1. Choose the Organization which you created our Github repository under.

2. Choose the repository that was set up earlier in this guide.

3. Select which branch that we want the build server to build into.

We can see which runtime stack and version we are running, in this example we are running .NET and Version 6.0.

Once the information has been added we can go ahead and preview the YAML file that will be used for the build server:

1. Save the workflow.

The website and the Github repository are now connected.

If we go back to the Github repository we can see that a new folder have been created called Workflows:

Inside the folder, we find that the YAML file has been created with the default settings from the Azure Portal. The file will need to be configured so it fits into your set up.

1. Pull down the new file and folder, so you can work with the YAML file on your local machine.

2. Configure it to work with our Umbraco Deploy installation.

When it have been configured it will look something like this:

We also need to add the License file and TriggerDeploy.ps1 file in an item group in the csproj file:

As well as enabling Unattended install in the appsettings.json file so Umbraco installs automatically:

Before the build can work, we will need to set up our generated API key to work with the build server in GitHub Actions.

1. Open your Github repository.

2. Navigate to Settings.

3. Go to the Secrets tab.

4. Select "New repository secret".

5. Call the new secret "DEPLOYAPISECRET".

6. Add the API secret from the appsettings.json file (replace ApiSecet with ApiKey in the script and use the corresponding value if you're using the deprecated API key setting instead).

7. Save the secret.

We can now go ahead and commit the configured YAML file and push up all the files to the repository.

Go to Github where you will now be able to see that the CI/CD build has started running:

The build server will go through the steps in the YAML file, and once it is done the deployment have gone through successfully:

You can now start creating content on the local machine. Once you create something like a Document Type, the changes will get picked up in Git.

When you're done making changes, commit them and deploy them to Github. The build server will run and extract the changes into the website in Azure.

This will only deploy the schema data for our local site to your website.

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

Background

When you deploy content or other Umbraco data between environments, some notifications that are normally fired in CMS operations are suppressed.

For example, you may handle a ContentPublishedNotification to apply some custom logic when a content item is published. This code will run in a normal CMS publish operation. However, when deploying a content item into another environment and triggering it's publishing there, the notification will not be issued. And the custom logic in the notification handler will not run.

This behavior is deliberate and done for performance and reliability reasons. A normal save and publish operation by an editor operates on one item at a time. With deployments, we may have many, and publishing these notifications may lead to at best slow operations, and at worst inconsistent data.

The notification will also already be published on the environment where the actual operation was carried out. So repeating this with each content transfer might also result in unwanted behavior.

However, what if you do want to run some code on an update, even if this is happening as part of a Deploy operation?

Not all notifications are suppressed by Umbraco Deploy. Some are batched and fired after the deploy operation is complete. These include those related to refreshing the Umbraco cache and rebuilding indexes.

You can use these cache refresher notifications to handle operations that should occur after a deployment is completed. All notification issued by the CMS are made available. So when deploying a set of content items, a refresher notification will be issued for each.

Implementing a Cache Refresher Notification

The following two code samples illustrate how this can be done.

The first handles a content cache refresher, which takes a payload from where the content ID can be extracted. Using that the content can be retrieved in the local Umbraco instance and used as appropriate.

For more details and further examples, please see the CMS Cache Refresher Notifications documentation.

using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Sync;

namespace TestSite.Business.NotificationHandlers;

public class ContentCacheRefresherNotificationHandler : INotificationHandler<ContentCacheRefresherNotification>
{
    private readonly ILogger<ContentCacheRefresherNotificationHandler> _logger;
    private readonly IContentService _contentService;

    public ContentCacheRefresherNotificationHandler(
        ILogger<ContentCacheRefresherNotificationHandler> logger,
        IContentService contentService)
    {
        _logger = logger;
        _contentService = contentService;
    }

    public void Handle(ContentCacheRefresherNotification notification)
    {
        // We only want to handle the RefreshByPayload message type.
        if (notification.MessageType != MessageType.RefreshByPayload)
        {
            return;
        }

        // Cast the payload to the expected type.
        var payload = (ContentCacheRefresher.JsonPayload[])notification.MessageObject;

        // Handle each content item in the payload.
        foreach (ContentCacheRefresher.JsonPayload item in payload)
        {
            // Retrieve the content item.
            var contentItemId = item.Id;
            IContent? contentItem = _contentService.GetById(contentItemId);
            if (contentItem is null)
            {
                _logger.LogWarning(
                    "ContentCacheRefresherNotification handled for type {MessageType} but content item with Id {Id} could not be found.",
                    notification.MessageType,
                    contentItemId);
                return;
            }

            // Do something with the content item. Here we'll just log some details.
            _logger.LogInformation(
                "ContentCacheRefresherNotification handled for type {MessageType} and id {Id}. " +
                "Key: {Key}, Name: {Name}",
                notification.MessageType,
                contentItemId,
                contentItem.Key,
                contentItem.Name);
        }
    }
}

The second example is similar, but handles an update to a dictionary item. With this one we get a parameter that consists of the item's ID. Again we can retrieve it and carry out some further processing.

using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Sync;

namespace TestSite.Business.NotificationHandlers;

public class DictionaryCacheRefresherNotificationHandler : INotificationHandler<DictionaryCacheRefresherNotification>
{
    private readonly ILogger<DictionaryCacheRefresherNotificationHandler> _logger;
    private readonly ILocalizationService _localizationService;

    public DictionaryCacheRefresherNotificationHandler(
        ILogger<DictionaryCacheRefresherNotificationHandler> logger,
        ILocalizationService localizationService)
    {
        _logger = logger;
        _localizationService = localizationService;
    }

    public void Handle(DictionaryCacheRefresherNotification notification)
    {
        // We only want to handle the RefreshById message type.
        if (notification.MessageType != MessageType.RefreshById)
        {
            return;
        }

        // Retrieve the dictionary item.
        var dictionaryItemId = (int)notification.MessageObject;
        IDictionaryItem? dictionaryItem = _localizationService.GetDictionaryItemById(dictionaryItemId);
        if (dictionaryItem is null)
        {
            _logger.LogWarning(
                "DictionaryCacheRefresherNotification handled for type {MessageType} but dictionary item with Id {Id} could not be found.",
                notification.MessageType,
                dictionaryItemId);
            return;
        }

        // Do something with the dictionary item. Here we'll just log some details.
        _logger.LogInformation(
            "DictionaryCacheRefresherNotification handled for type {MessageType} and id {Id}. " +
            "Key: {Key}, Default Value: {DefaultValue}",
            notification.MessageType,
            dictionaryItemId,
            dictionaryItem.ItemKey,
            dictionaryItem.GetDefaultValue());
    }
}

In both cases, as is usual for notification handlers, you will need to register them via a composer:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Notifications;
using TestSite.Business.NotificationHandlers;

namespace TestSite.Business;

public class SiteComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddNotificationHandler<ContentCacheRefresherNotification, ContentCacheRefresherNotificationHandler>();
        builder.AddNotificationHandler<DictionaryCacheRefresherNotification, DictionaryCacheRefresherNotificationHandler>();
    }
}

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

{
  ...
  "Umbraco": {
    "CMS": {
        ...
    },
    "Deploy": {
        ...
    }
  }
}

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.

{
  ...
  "Umbraco": {
    "Deploy": {
        "Settings": {
            "ApiKey": "<your API key here>",
            "ApiSecret": "<your API secret here>",
            "Edition": "Default",
            "ExcludedEntityTypes": [],
            "RelationTypes" : [],
            "ValueConnectors": [],
            "SessionTimeout": "0.0:20:00",
            "SourceDeployTimeout": "0.0:20:00",
            "DatabaseCommandTimeout": "0.0:20:00",
            "EnableSignatureCacheReads": true,
            "HttpClientTimeout": "0.0:20:00",
            "DiskOperationsTimeout": "0.0:05:00",
            "SourceDeployBatchSize": null,
            "PackageBatchSize": null,
            "MaxRequestLength": null,
            "UseDatabaseBackedTransferQueue": true,
            "IgnoreBrokenDependenciesBehavior": "Restore",
            "AcceptInvalidCertificates": false,
            "TransferFormsAsContent": true,
            "TransferDictionaryAsContent": false,
            "IgnoreMissingLanguagesForDictionaryItems": false,
            "SetEmptyDictionaryItemsOnTransfer": true,
            "AllowMembersDeploymentOperations": "None",
            "TransferMemberGroupsAsContent": false,
            "ExportMemberGroups": true,
            "ReloadMemoryCacheFollowingDiskReadOperation": false,
            "AllowDomainsDeploymentOperations": "None",
            "AllowWebhooksDeploymentOperations": "None",
            "TrashedContentDeploymentOperations": "Import",
            "PreferLocalDbConnectionString": false,
            "MediaFileChecksumCalculationMethod": "PartialFileContents",
            "NumberOfSignaturesToUseAllRelationCache": 100,
            "ContinueOnMediaFilePathTooLongException": false,
            "SuppressCacheRefresherNotifications": false,
            "ResolveUserInTargetEnvironment": false,
            "Suspensions": {
              "DiskRead": "All",
              "PartialRestore": "All",
              "Restore": "All",
              "Deploy": "All",
              "Import": "All",
              "Export": "All"
            },
            "HideConfigurationDetails": false,
            "HideVersionDetails": false
        }
    }
  }
}

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:

"ExcludedEntityTypes": ["media-file"],

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.

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

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

This setting is used by package creators who want their custom editors to work with Deploy. The packages should be creating this setting automatically. There is a community-driven package that has value connectors for Deploy called Deploy Contrib.

Here is an example of how the setting can look:

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

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.

All of these times are configured using standard timespan format strings.

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.

MaxRequestLength

When Deploy transfers files between unconnected environments (like a non-public local environment), it falls back from fetching/downloading the files to uploading them. This is done in fixed-sized chunks, so multiple files can be combined in a single request or a large file into multiple requests. This setting can specify the size of these chunks (in bytes).

If no value is set, Deploy will create 16MB chunks, unless the CMS MaxRequestLength setting is lower (CMS setting is configured in kilobytes). Setting a value higher than the CMS MaxRequestLength (multiplied by 1024) will cause a validation error. Similarly, configuring a value higher than the server or infrastructure limits will result in file transfers failures.

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.

    "IgnoreBrokenDependenciesBehavior": "Restore",

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:

    "IgnoreBrokenDependencies": true,
    "IgnoreBrokenDependenciesBehavior": "Restore",

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:

    "ReloadMemoryCacheFollowingDiskReadOperation": true,

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.

    "AllowDomainsDeploymentOperations": "None|Culture|AbsolutePath|Hostname|All",

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.

    "AllowPublicAccessDeploymentOperations": "None|AddOrUpdate|Remove|All",

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

    "AllowWebhooksDeploymentOperations": "None|All",

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:

"TrashedContentDeploymentOperations": "None|Export|Import|All"

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.

"PreferLocalDbConnectionString": true

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:

  "Suspensions": {
    "PartialRestore": "ScheduledPublishing, DocumentCache"
  }

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

  "Suspensions": "ScheduledPublishing, DocumentCache, Signatures"

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

using Umbraco.Cms.Core.Composing;
using Umbraco.Deploy.Core.Configuration.DeployConfiguration;

internal class DeploySuspensionComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<DeploySettings>(options =>
        {
            // No suspensions during import
            options.Suspensions.Import = SuspensionOptions.None;

            // No Examine suspensions on all operations (using bitwise negation operator)
            options.Suspensions &= ~SuspensionOptions.Examine;

            // Add scheduled publishing suspension to all operations
            options.Suspensions |= SuspensionOptions.ScheduledPublishing;
        });
}

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.

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

public class RegisterDeployWebhooksComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.WebhookEvents().AddDeploy(deployBuilder => deployBuilder.AddTask());
}

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:

{
  "Id": "dc93c9ec-fbc9-4be4-91ad-f195e0c12f43",
  "WorkItemType": "DiskReadWorkItem",
  "Environment": {
    "Name": "Live",
    "Uri": "https://localhost:44309"
  },
  "Result": "Completed",
  "Duration": "00:00:00.8125947",
  "Udis": [
    "umb://document-type/a0b5933193b8460c8eda57408f088a2e"
  ]
}

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();
    }
}

Registration

With the artifact and connectors in place, the final step necessary is to register your entity for deployment.

Connectors do not need to be registered. The fact that they inherit from particular interfaces known to Umbraco Deploy is enough to ensure that they will be used.

Custom Entity Types

If custom entity types are introduced that will be handled by Umbraco Deploy, they need to be registered with Umbraco to parse the UDI references.

This is done via the following code, which can be triggered from a Umbraco component or an UmbracoApplicationStartingNotification handler.

UdiParser.RegisterUdiType("mypackage-example", UdiType.GuidUdi);

Disk Based Transfers

To deploy the entity as schema, via disk based representations held in .uda files, it's necessary to register the entity with the disk entity service. This is done in a component, where events are used to trigger a serialization of the entity to disk whenever one of them is saved.

public class ExampleDataDeployComponent : IComponent
{
    private readonly IDiskEntityService _diskEntityService;
    private readonly IServiceConnectorFactory _serviceConnectorFactory;
    private readonly IExampleDataService _exampleDataService;

    public ExampleDataDeployComponent(
        IDiskEntityService diskEntityService,
        IServiceConnectorFactory serviceConnectorFactory,
        IExampleDataService exampleDataService)
        {
            _diskEntityService = diskEntityService;
            _serviceConnectorFactory = serviceConnectorFactory;
            _exampleDataService = exampleDataService;
        }

    public void Initialize()
    {
        _diskEntityService.RegisterDiskEntityType("mypackage-example");
        _exampleDataService.ExampleSaved += ExampleOnSaved;
    }

    private void ExampleOnSaved(object sender, ExampleEventArgs e)
    {
        var artifact = GetExampleArtifactFromEvent(e);
        _diskEntityService.WriteArtifacts(new[] { artifact });
    }

    private IArtifact GetExampleArtifactFromEvent(ExampleEventArgs e)
    {
        var udi = e.Example.GetUdi();
        return _serviceConnectorFactory.GetConnector(udi.EntityType).GetArtifact(e.Example);
    }

    public void Terminate()
    {
    }
}

Including Plugin Registered Disk Entities in the Schema Comparison Dashboard

In Umbraco Deploy 9.4 a schema comparison feature was added to the dashboard available under Settings > Deploy. This lists the Deploy managed entities held in Umbraco and shows a comparison with the data held in the .uda files on disk.

All core Umbraco entities, such as Document Types and Data Types, will be shown.

To include entities from plugins, they need to be registered using a method overload as shown above, that allows to provide additional detail, e.g.:

_diskEntityService.RegisterDiskEntityType(
    "mypackage-example",
    "Examples",
    false,
    _exampleDataService.GetAll().Select(x => new DeployDiskRegisteredEntityTypeDetail.InstalledEntityDetail(x.GetUdi(), x.Name, x))));

The parameters are as follows:

• The system name of the entity type (as used in the UdiDefinition attribute).

• A human readable, pluralized name for display in the schema comparison dashboard user interface.

• A flag indicating whether the entity is an Umbraco one, which should be set to false.

• A function that returns all entities of the type installed in Umbraco, mapped to an object exposing the Udi and name of the entity.

Backoffice Integrated Transfers

If the optimal deployment workflow for your entity is to have editors control the deployment operations, the transfer entity service should be used. This would be instead of registering with the disk entity service. The process is similar, but a bit more involved. There's a need to also register details of the tree being used for editing the entities. In more complex cases, we also need to be able to handle the situation where multiple entity types are managed within a single tree.

An introduction to this feature can be found in the second half of this recorded session from Codegarden 2021.

There's also a code sample, demonstrated in the video linked above, available here.

The following code shows the registration of an entity for Backoffice deployment, where we have the simplest case of a single tree for the entity.

public class ExampleDataDeployComponent : IComponent
{
    private readonly ITransferEntityService _transferEntityService;
    private readonly IExampleDataService exampleDataService;

    public ExampleDataDeployComponent(
        ITransferEntityService transferEntityService,
        IExampleDataService exampleDataService)
    {
        _transferEntityService = transferEntityService;
        _exampleDataService = exampleDataService;
    }

    public void Initialize()
    {
        _transferEntityService.RegisterTransferEntityType(
            "mypackage-example",
            "Examples",
            new DeployRegisteredEntityTypeDetailOptions
            {
                SupportsQueueForTransfer = true,
                SupportsQueueForTransferOfDescendents = true,
                SupportsRestore = true,
                PermittedToRestore = true,
                SupportsPartialRestore = true,
            },
            false,
            "exampleTreeAlias",
            (string routePath, HttpContext httpContext) => true,
            (string nodeId, HttpContext httpContext) => true,
            (string nodeId, HttpContext httpContext, out Guid entityId) => Guid.TryParse(nodeId, out entityId),
            new DeployRegisteredEntityTypeDetail.RemoteTreeDetail(FormsTreeHelper.GetExampleTree, "example", "externalExampleTree"),
            entitiesGetter: () => _exampleDataService.Get());
    }

    public void Terminate()
    {
    }
}