Transformations in asp.net is an easy way to automatically set your configurations in different environments. An example of this would be when we want our connection strings, usernames, passwords,  proxies, etc. to be different in our development environment from our production environment.  Since the web.config file is written in xml, we use XML Document-Transform(xdt) to make the transformations.

In your VisualStudio project every web.config has a Web.Debug.config  and Web.Release.config. If you have never used transformations before, you probably don't know what these files are for.

Web.Config:

1
2
3
4
5
6
7
8
9
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="SPath" value="C:\Users\file.txt" />
  </appSettings>
  <system.web>
    <compilation debug="true" targetFramework="4.5.1" />
  </system.web>
</configuration>

Web.Release.Config:

1
2
3
4
5
6
7
8
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <appSettings>
    <add key="SPath" value="D:\Program File\path.txt"  xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
  </appSettings>
  <system.web>
    <customErrors mode=\"On\" xdt:Transform=\"Insert\"></customErrors>
  </system.web>
</configuration>

Changes this transformation file does:

  • It will match the key SPath and change the value to D:\Program File\path.txt.
  • It will replace the customErrors tag with mode=\"On\".

If you try to use xdt:Transform=\"Replace\" and your web.config file does not contain what you are trying to replace, it will be added.

Check out the Microsoft documentation for more examples.