From 98b0f816bcec4902a2c07c1c0d81f9126c3cdf99 Mon Sep 17 00:00:00 2001 From: Sofie Toft Date: Thu, 4 Sep 2025 08:56:58 +0200 Subject: [PATCH 1/2] Update config transform article and linked between the 2 --- .../project-features/environments.md | 2 ++ .../project-settings/config-transforms.md | 36 ++++++------------- 2 files changed, 12 insertions(+), 26 deletions(-) diff --git a/umbraco-cloud/begin-your-cloud-journey/project-features/environments.md b/umbraco-cloud/begin-your-cloud-journey/project-features/environments.md index 31573a521c2..849fd294db6 100644 --- a/umbraco-cloud/begin-your-cloud-journey/project-features/environments.md +++ b/umbraco-cloud/begin-your-cloud-journey/project-features/environments.md @@ -61,6 +61,8 @@ The `EnvironmentAlias` is fetched from the Environment variable named `DOTNET_EN The value of the `DOTNET_ENVIRONMENT` environment variable can be managed through the **Advanced** settings in the **Configuration** section of the Cloud Portal. +Learn more about how to transform configuration files in the [Config Transforms](../../build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md) article. + {% hint style="info" %} When you start up the Umbraco Application, ensure you load the correct JSON file as per the ASP.NET Configuration in the official [Microsoft documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-9.0). diff --git a/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md b/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md index 835ff55455b..19b1cd1dba6 100644 --- a/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md +++ b/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md @@ -14,29 +14,27 @@ Common configuration files, like the `web.config` and `appSettings.json` files o 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`. +To transform a config file, you need to create a new file in your project with the following naming convention: `{config-file name}.{environmentAlias}.config`. {% hint style="info" %} **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 [Legacy Documentation](https://github.com/umbraco/UmbracoDocs/blob/legacy-cloud/Umbraco-Cloud/Set-Up/Config-Transforms/index.md). +If your project is on Umbraco 7 and 8 the naming convention is the following: `{config-file name}.{environmentAlias}.xdt.config.` Find more details on this in the [Legacy Documentation](https://github.com/umbraco/UmbracoDocs/blob/legacy-cloud/Umbraco-Cloud/Set-Up/Config-Transforms/index.md). {% endhint %} -To transform your `Web.config` file for the Live environment, create a config transform that looks like this: +To transform your `appSetttings.json` file for an environment with the alias "Live", create a config transform that looks like this: -`Web.Production.config` +`appSettings.Live.json` -The `{environment}` part needs to be replaced with the target environment, for which there are currently three possibilities for each project: +The `{environmentAlias}` part needs to be replaced with the target environments alias. The environment aliases is fetched from the environment variable named `DOTNET_ENVIRONMENT`. -1. `Production` -2. `Staging` -3. `Development` +You can find and manage the value of the `DOTNET_ENVIRONMENT` environment variable through the **Advanced** settings in the **Configuration** section of the Cloud Portal. -Create this file in your local project clone to ensure it's added to the repository. +Create the files in your local project clone to ensure it's added to the 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. +When the file is deployed to the Live environment, the transforms will be applied to the `appSettings.json` file in the `Root` of your project. In the case that you have mutliple mainline environments, the `appSettings.Live.json` will **only** transform the `appSettings.json` 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. +For each deployment, the Umbraco Cloud engine searches for all of the `.{environment}.json` files in your site and apply the transforms. {% hint style="info" %} Using config transforms to remove and/or add sections to config files is currently only possible for the `Web.config` file. @@ -58,7 +56,7 @@ Before applying the config transform files to your environments, we recommend ru 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 +## Examples (web.config) 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. @@ -92,17 +90,3 @@ The snippet requires a `web.config` file with a matching structure; otherwise, t {% endhint %} This config transform will add a `` to ``. 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. - -![appSettings.json transforms](images/appSettings.png) - -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. From 241750de74ede167d085d380a200fb9e16ee60c5 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Thu, 4 Sep 2025 10:47:11 +0200 Subject: [PATCH 2/2] Update umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md Co-authored-by: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> --- .../set-up-your-project/project-settings/config-transforms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md b/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md index d89503464c5..499b31ce16b 100644 --- a/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md +++ b/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/config-transforms.md @@ -26,7 +26,7 @@ To transform your `appSetttings.json` file for an environment with the alias "Li `appSettings.Live.json` -The `{environmentAlias}` part needs to be replaced with the target environments alias. The environment aliases is fetched from the environment variable named `DOTNET_ENVIRONMENT`. +The `{environmentAlias}` part needs to be replaced with the target environment's alias. The environment alias is fetched from the environment variable named `DOTNET_ENVIRONMENT`. You can find and manage the value of the `DOTNET_ENVIRONMENT` environment variable through the **Advanced** settings in the **Configuration** section of the Cloud Portal.