Umbraco Cloud
CMSHeartcoreDXPMarketplace
  • What is Umbraco Cloud?
  • Frequently asked questions
  • Security
    • Web Application Firewall
  • Sustainability Best Practices
  • Getting Started
    • Explore Umbraco Cloud
    • The Cloud Portal
      • Organizations
      • Sustainability Dashboard
    • Project Overview
    • Environments
    • Flexible Environments (beta)
    • Baselines
      • Baseline Merge Conflicts
      • Break Reference between Baseline and Child Project
      • Handling configuration files
      • Pushing Upgrades to a Child Project
    • Plans
    • Migrate to Umbraco Cloud
    • Repositories in a Cloud Project
    • Best Practice for Working in Teams
    • Migrate between regions
  • Set up
    • Ready to Set Up Your Project?
    • Working with a Local Clone
      • Legacy Umbraco Visual Studio Setup
    • Manage Environments
    • Project Settings
      • Managing Transport Security
      • CDN Caching and Optimizations
      • Dedicated Resources
      • Upgrade your Plan
      • Public Access
      • Managing Hostnames
        • New Certificate Authority for custom hostnames
        • Rewrite rules
        • Custom Certificates
      • Management API Security
      • Umbraco CI/CD Flow
        • Cloud API For CI/CD Flow
        • Configuring a CI/CD pipeline
          • Azure DevOps
          • GitHub Actions
        • Troubleshooting
        • Known Limitations and Considerations
      • External Services
      • Usage
        • Bandwidth
      • Availability and Performance
      • Team Members
        • Technical Contact
      • Secrets Management
      • Project History
    • Private NuGet Feed on Umbraco Cloud
    • Going Live
    • Media
    • External Login Providers
    • Azure Blob Storage
      • Connect to Azure Storage Explorer to upload files manually
      • Connect and Upload Files Programmatically to Azure Blob Storage
    • Users
    • Multi-Factor Authentication
    • Application Insights
    • Config Transforms
    • SMTP Settings
    • Payments
      • Subscription migration information and FAQ
    • Power Tools (Kudu)
      • View the Files on your Cloud Environments
      • Generate UDA files
      • Manually run Extractions on your Cloud Environments
  • Deployments
    • Deployment
    • Deploying between environments
    • Transferring Content, Media, Members, and Forms
    • Deploying Deletions
    • Deployment Webhook
    • Deploying Changes
    • Umbraco Forms on Cloud
    • Deploy Dashboard
    • Hotfixes
      • Apply hotfix by manually moving files
      • Apply hotfix by using Git
    • Restoring Content
      • Partial Restores
  • Databases
    • Keep Your Data Secure and Accessible
    • Working with databases
    • Database backups
    • Database
      • Connecting to the Database on Mac
    • Working with a Cloud database locally
  • Product Upgrades
    • Stay Up to Date with Umbraco Cloud
    • Product Upgrades
    • Major Upgrades
    • Minor Upgrades
    • Version Specific Upgrades
      • Migrate from Umbraco 8 to the latest version
      • Migrate from Umbraco 7 to Umbraco 8 on Umbraco Cloud
    • Upgrade your projects manually
      • Manual upgrade of Umbraco CMS
      • Manual upgrade of Umbraco Deploy
    • Dependencies on Umbraco Cloud
  • Troubleshooting
    • Resolve Issues Quickly and Efficiently
    • Troubleshooting FAQ
    • Log files
    • The Umbraco Backoffice
    • The Frontend
    • The Umbraco Cloud Portal
    • Site Performance checklist
    • Troubleshooting deployments
      • Extraction error: Config transforms failing
      • Extraction error: Data Type collisions
      • Dependency Exception
      • Merge Conflicts on Flexible Environments
      • Troubleshooting deployments failing with no error message
      • Troubleshooting duplicate dictionary items
      • Troubleshooting language mismatches
      • Path too long Exception
      • Schema Mismatches
      • How to resolve collision errors
      • Extraction error: "Type not found! "
    • Cloud Errors
  • Release Notes
    • Overview 2025
      • April 2025
      • March 2025
      • February 2025
      • January 2025
    • Overview 2024
      • December 2024
      • November 2024
      • October 2024
      • September 2024
      • August 2024
      • July 2024
      • May 2024
      • April 2024
      • March 2024
      • February 2024
      • January 2024
    • Overview 2023
      • December 2023
      • October 2023
      • September 2023
      • August 2023
      • June 2023
      • May 2023
      • April 2023
      • March 2023
      • February 2023
      • January 2023
    • Overview 2022
      • December 2022
      • November 2022
      • September 2022
      • August 2022
      • June 2022
      • May 2022
      • April 2022
      • March 2022
      • February 2022
      • January 2022
Powered by GitBook
On this page
  • What are Config Transforms?
  • Syntax and testing
  • Examples
  • appsettings.json transforms

Was this helpful?

Edit on GitHub
Export as PDF
  1. Set up

Config Transforms

Configuration files can be transformed to match requirements on different Umbraco Cloud environments.

PreviousApplication InsightsNextSMTP Settings

Last updated 1 month ago

Was this helpful?

In this article, you will find examples of applying environment-specific configuration to your Umbraco Cloud project.

Common configuration files, like the web.config and appSettings.json files on your Umbraco Cloud project will be used as examples.

What are Config Transforms?

Config Transforms are a way to transform your config files without changing the actual config file.

To transform a config file, you need to create a new file in your project with the following naming convention: {config-file name}.{environment}.config.

Legacy Umbraco

If your project is on Umbraco 7 and 8 the naming convention is the following: {config-file name}.{environment}.xdt.config. Find more details on this in the .

If you want to do a transform on your Web.config file for the Live environment of your project, the config transform you need to create will look like this:

Web.Production.config

The {environment} part needs to be replaced with the target environment, for which there are currently three possibilities for each project:

  1. Production

  2. Staging

  3. Development

This file needs to be created on a local clone of your project, as this will ensure that the file is added to the project repository.

When the file is deployed to the Live environment, the transforms will be applied to the Web.config file in the Root of your project. In the case that you have mutliple mainline environments, the Web.Production.config will only transform the Web.config on the Live environment.

For each deployment, the Umbraco Cloud engine searches for all of the .{environment}.config files in your site and apply the transforms.

Using config transforms to remove and/or add sections to config files is currently only possible for the Web.config file.

Syntax and testing

When creating config transforms you need to follow these three rules:

  1. Use the correct file-naming convention.

  2. Place the transform file in the same folder as the file you want to transform.

Using the tool will let you test whether the transform file transforms your config files correctly. The tool can be used for all config files.

Examples

Rewrite rules are often something you only want to apply to your Live environment. To avoid the rewrites being applied to other mainline environments, create a transform file to apply the rewrite rules only to the Live environment.

Here is an example of how that config transform would look:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
	<system.webServer>
		<rewrite>
			<rules>
				<rule xdt:Transform="Insert" name="Redirects umbraco.io to actual domain" stopProcessing="true">
					<match url=".*" />
					<conditions>
						<add input="{HTTP_HOST}" pattern="^(.*)?.euwest01.umbraco.io$" />
						<add input="{REQUEST_URI}" negate="true" pattern="^/umbraco" />
						<add input="{REQUEST_URI}" negate="true" pattern="^/DependencyHandler.axd" />
						<add input="{REQUEST_URI}" negate="true" pattern="^/App_Plugins" />
						<add input="{REQUEST_URI}" negate="true" pattern="localhost" />
					</conditions>
					<action type="Redirect" url="https://mycustomwebsite.com/{R:0}" appendQueryString="true" redirectType="Permanent" />
				</rule>
			</rules>
		</rewrite>
	</system.webServer>
</configuration>

The above snippet requires your project to have a web.config file with a matching structure, otherwise, the config transform (and subsequently, the deployment) might fail.

This config transform will add a <rule> to <system.webServer><rewrite><rules>. The xdt:Transform attribute is used to tell the system what to transform. In this case, the value is Insert, which means it will add the section if it's not already in the config file.

appsettings.json transforms

On Umbraco Cloud, projects come with an appsettings.json file for each of your different environments.

With this, you can add different environment-specific settings to your project.

To edit the appsettings.json files for the different environments, the Umbraco Cloud project needs to be cloned down to your local machine. Then the files can be edited using your code editor.

Once done editing the files, they will need to be pushed up to your Umbraco Cloud project to be added to the repository.

When the file is deployed to the next environment on Umbraco Cloud, the settings in the appsettings file will be applied to that environment. For example, the settings in the appsettings.Production.json will be applied to the Live environment of your project.

Be aware that a misconfigured config transform may .

Follow the correct .

Before applying the config transform files to your environments, we recommend running a test using this tool: .

Legacy Documentation
block Data Extraction on your project
Config Transform syntax
Webconfig Transformation Tester
appSettings.json transforms