Handling configuration files

Learn how to handle configuration files when working with Baseline and Child projects on Umbraco Cloud.

This article only applies to Umbraco Cloud projects running Umbraco versions 7 or 8.

When developing with a Baseline setup, there are a few things to keep in mind when updating configuration files.

When deploying updates from the Baseline to Child projects, all solvable merge conflicts on configuration files are resolved using the Child project's settings.

If a file has been changed in both the Baseline and the Child project, the Baseline change will not be applied to the Child. To have custom settings on the Child project, you should take advantage of the vendor-specific transform files.

On Umbraco Cloud, it is possible to create transform files that will be applied to certain environments by naming them like web.live.xdt.config (see Config-Transforms). This should be used when a Child project needs different settings than the Baseline project.

It can be achieved by using a configuration file that is specific to the Child Project, naming it like child.web.live.xdt.config. This file should only be in the Child project's repository. Create the file locally and push it directly to the Child project. Read the Working locally article to learn more about how this is done.

Following this workflow will ensure that when the Child is updated from the Baseline, the settings won't be overwritten.

This practice is especially important when the Baseline project receives major new functionality. This includes new code that depends on configuration files, or when upgrades are applied.

When you need a specific configuration on Child projects, always use config transforms.

Editing default config files on the Child project directly may prevent you from pushing changes from your Baseline project in the future.

Examples

Adding or updating appsettings

child-appsettings.web.live.xdt.config

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings xdt:Transform="InsertIfMissing">
        <!-- Updates the value of the appSetting called owin:appStartup -->
        <add key="owin:appStartup" value="MyCustomOwinStartup" xdt:Locator="Match(key)" xdt:Transform="SetAttributes(value)" />
        <!-- Adds the appsetting MyOwnAppSetting, if it isn't already there -->
        <add key="MyOwnAppSetting" value="AmazingValue" xdt:Locator="Match(key)" xdt:Transform="InsertIfMissing" />
        <!-- Ensures a custom value is there and set to a certain value (remove and add) -->
        <add key="MyOwnAppSetting2" xdt:Locator="Match(key)" xdt:Transform="RemoveAll" />
        <add key="MyOwnAppSetting2" value="AmazingValue2" xdt:Locator="Match(key)" xdt:Transform="InsertIfMissing" />
    </appSettings>
</configuration>

Setting the Simple Mail Transfer Protocol (SMTP) settings for the child project

child-smtpsettings.web.live.xdt.config

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.net xdt:Transform="InsertIfMissing">
        <mailSettings xdt:Transform="InsertIfMissing">
            <smtp xdt:Transform="RemoveAll" />
            <smtp from="[email protected]" xdt:Transform="InsertIfMissing">
                <network host="smtp.sendgrid.com" userName="abc" password="def" />
            </smtp>
        </mailSettings>
    </system.net>
</configuration>

Setting custom rewrite rules for the child project

child-iisrewrite.web.live.xdt.config

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <rewrite xdt:Transform="InsertIfMissing">
            <rules xdt:Transform="InsertIfMissing">
                <rule xdt:Locator="Match(name)" xdt:Transform="InsertIfMissing" 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="http://childdomain.dk/{R:0}" appendQueryString="true" redirectType="Permanent" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

The above could either be added to its config files or be split up into one config file per setting. Umbraco Cloud will run through all the config files for the project.

• child.web.live.xdt.config

or having multiple files

• child-appsettings.web.live.xdt.config
• child-iisrewrite.web.live.xdt.config
• child-smtpsettings.web.live.xdt.config