Tutorial

How to use the Replace Token task

This page will show you how you can use the Replace Token task in your deployment.

Context

We have a web application with the following web.config file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="mydb" connectionString="Data Source=(localdb)\mssqllocaldb;Initial Catalog=mydb;Integrated Security=True" />
  </connectionStrings>

  <appSettings>
    <add key="environment" value="LOCAL" />
  </appSettings>

  <system.web>
    <compilation debug="true" />
  </system.web>
</configuration>

We need to be able to run and deploy this web app with the following constraints:

1. We build only one package and deploy to multiple environment (only the connection string and the environment app setting change between environment)
2. We need to be able to launch and debug locally without any specific actions

Build one package / deploy to multiple environment

For the first constraint we need to have a tokenized web.config file so that we can replace at deployment time those token with values for the environment using the Replace Token task.

The web.config file must look like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="mydb" connectionString="Data Source=#{database.server}#;Initial Catalog=#{database.name}#;User ID=#{database.user}#;Password=#{database.password}#" />
  </connectionStrings>

  <appSettings>
    <add key="environment" value="#{environment}#" />
  </appSettings>

  <system.web>
    <compilation />
  </system.web>
</configuration>

And we will declare the following variables at the environment scope in the VSTS/TFS release definition:

• database.server
• database.name
• database.user
• database.password (don't forget to make it a secret variable 😄)
• environment

Easy local debugging

For the second constraint, to have an easy developer and debug experience the web.config file must be configured with local values so that we can just F5 to launch the debugger and not tokenized as needed for the first constraint.

To resolve this dilemma we must use another tool: XDT transforms. We will use this to replace attributes values with our tokens. This can be done just after the build and before creating our deployment package or at deployment time just before replacing tokens. I would suggest doing it at deployment time so that you can do more advance stuff like different transformations based on the environment.

For our example we can use this web.release.config file to do the transformation:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <connectionStrings>
    <add name="mydb" 
         connectionString="Data Source=#{database.server}#;Initial Catalog=#{database.name}#;User ID=#{database.user}#;Password=#{database.password}#" />
         xdt:Transform="SetAttributes" 
         xdt:Locator="Match(name)" />
  </connectionStrings>

  <appSettings>
    <add key="environment" 
         value="#{environment}#"
         xdt:Transform="SetAttributes" 
         xdt:Locator="Match(key)" />
  </appSettings>

  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

This transformation file will:

• replace the connection string mydb with a tokenized value
• replace the environment app setting with a tokenized value
• remove the debug attribute.

To be able to apply XDT transformations during a build or release in VSTS/TFS you can use my XDT Transform task.

Configure VSTS/TFS release definition

Let's see how this all fit together in a release definition assuming you have the web.config and web.release.config files in your build artifact.

1. Create a release definition and add your build artifact.
2. Create your first environment.
3. Add the XDT Transform task and configure it to apply the transformation.
4. Add the Replace Token task and configure it to replace tokens in your newly updated web.config.
5. Add the relevant variables and their value in the environment variables.
6. Create your next environment by cloning the previous one and setup the variables.

Note that this can be applied to any XML file.