XDT configuration transforms

XML Document Transform (XDT) is the xdt:Transform syntax behind files like Web.Release.config. Out of the box, Visual Studio applies these transforms when you publish, once per build configuration. fDeploy Agent applies them at deploy time instead, per target environment, so one package can go to Test and Production with different configuration. It also works on any XML file, not just web.config.

How it works

During deployment, configuration transforms run after the package is extracted and before variable substitution. This means you can combine XDT transforms with fDeploy variable substitution for maximum flexibility.

The deployment pipeline order is:

1. Package upload and extraction
2. Configuration transforms
3. Variable substitution
4. Certificate installation
5. IIS configuration

XDT syntax

Transform files use the Microsoft XML Document Transform namespace. Here is an example of a transform file that removes the debug attribute from the compilation element:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

For more information on XDT syntax, refer to the Microsoft documentation on web.config transforms.

Automatic transforms

When the “Automatically run .NET configuration transformation files” checkbox is enabled on an IIS deployment step, fDeploy Agent will scan your deployed package for transform files that follow the standard naming convention and apply them automatically.

Transform files are applied in this order:

1. *.Release.config
2. *.<Environment>.config

For example, suppose your package contains:

Web.config
Web.Release.config
Web.Production.config
Web.Test.config

When deploying to an environment named “Production”, fDeploy Agent will:

1. Apply Web.Release.config to Web.config
2. Apply Web.Production.config to Web.config

The Web.Test.config file will not be applied since the target environment is “Production”, not “Test”.

Note

Transform files are deleted after they are successfully applied. The target file (e.g. Web.config) is modified in place.

Tip

This convention works for any XML file, not just web.config. For example, if you have app.config, app.Release.config, and app.Production.config, fDeploy will transform them in the same way.

Additional transforms

You can define additional transforms in the “Additional transforms” text field. These transforms run regardless of whether the automatic transforms checkbox is enabled. This is useful when your transform files do not follow the standard naming convention.

Additional transforms are defined using the format:

TransformFile => TargetFile

One transform definition per line. fDeploy supports three types of definitions:

Explicit

Transform.config => Target.config

Applies Transform.config to Target.config when both files are in the same directory. fDeploy will search recursively through all directories in your package for matching pairs.

Relative path

Path\Transform.config => Target.config

Applies Transform.config to Target.config when Transform.config is in the directory Path relative to Target.config.

Wildcard

Wildcards can be used to match multiple files. They can be used anywhere in the transform filename (left side), but only at the start of the target filename (right side).

Wildcard on both sides:

*.Transform.config => *.config

Applies foo.Transform.config to foo.config and bar.Transform.config to bar.config.

Wildcard on transform only:

*.Transform.config => Target.config

Applies foo.Transform.config and bar.Transform.config to the same Target.config.

Wildcard on target only:

Transform.config => Path\*.config

Applies Transform.config to foo.config and bar.config when foo.config and bar.config are in the directory Path relative to Transform.config.

Note

Target files must already exist in your package. fDeploy will not create new files from transforms.