How to web.config transform using VSTS Release Management

VSTS is a powerful tool that houses the CI/CD portion of development.  Previously, it was good practice to create a gated check in definition that did a quick release build to prevent developers from checking in broken code, followed by a full CI build definition that built for all your environments.  While this worked, and the separation between GCI and CI build definitions allowed developers to reconcile their workspace much faster, VSTS has updated their deployment task to 3.0 and added the ability to transform web.configs during deployment.

However, the process isn’t well documented yet and there are a few “gotchyas” that should be noted.

Transform files must be “independent” of the original Web.config

When you create transforms through VS, the transforms are nested under the Web.config (eg Web.Dev.config, Web.Release.config, Web.Debug.config, etc).  When VSTS builds your solution, chances are you’re running it in the Release configuration.  This will automatically run the Web.Release.config and then delete all the other transformation files when zipping it up for deployment.  To prevent this deletion of transformation files, unload the project in VS, edit the project file, and remove all the <DependentUpon> nodes from the transformation files in the XML.


Stop using Release for your production configuration

As part of the task’s code, the transformations will be run based on naming convention.  For instance, if you have for environments in your release definition (Dev, QA, Staging, Prod), you must have matching transformation files if you want to transform anything (Web.Dev.config, Web.QA.config, Web.Staging.config, Web.Prod.config).

However, if you have a Web.Release.config, that will be run BEFORE your environment transformation file, and it will be run for EVERY environment.  While some might see this as offensive, it’s actually really nice as you can move duplicated transformations to the Release transformation file and you don’t need to duplicate that.

In any case, let it be known that your production environment should be named something other than Release.

Transformation files must have build action “Content”

Web.config, Debug.config and Release.config are already set, but your environmental configurations must have their properties updates in the project so their build action is “Content.”  This will include them in the release package artifact.

Connection strings parameterization needs to be turned off

When you build with MSDeploy, MSDeploy will automatically output a parameterization file that will include connection strings.  This means that it will keep the original found in Web.config, and even if you transform them in your environment transformation file, the parameter file will overwrite it.  To prevent this, just add this to your MSDeploy command line parameters:


Turn on transformations in the release definition

With the above steps done, you’re now ready to turn on transformations and trash your CI build definition.




Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a website or blog at

Up ↑

%d bloggers like this: