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.



17 thoughts on “How to web.config transform using VSTS Release Management

Add yours

  1. Yes, great article… wish the task would not need to require those hacks. One thing is that now all web.environment.config files are also copied to the final destination Azure app. Any suggestion on how to avoid that ? Or maybe with a task to delete the superfluous files afterwards ?


    1. Hey Mathieu,

      Yes, this does leave every web.config transformation file up on every server you deploy to. Unfortunately, this is a byproduct of the process. However, the transforms don’t hurt the application as they are ignored. If you’re worried about cleanliness or someone FTPing up into the server and seeing prod transforms (though really, that shouldn’t matter since these transforms are part of your solution and thus seen by everyone who has access to the code), you can definitely use a task to blow them away. Here is a task to do such a thing:


  2. This was really helpful! I was able to get the web.Release.config working!
    Any ideas why I cannot get my working? Where does the VSTS build grab the environment from?
    I have been working on this all day but to no avail.


    1. The process will run up to two transforms: the web.Release.config and the environmental one. I’m not sure if it’s case-sensitive, as I’ve always matched case on the naming of my environment and my transform, but you could try that.

      For instance, if your first environment (dev) is named “dev”, try to name your web.config translation, not web.Dev.config nor web.Development.config, etc. Try to match it exactly.

      Let me know how it turns out for you.

      Liked by 1 person

      1. I got it! It turns out that the XML Transform chooses which environment.config is used based on the ‘Release.EnvironmentName’ variable. If finally found this by looking at the code on github.

        After all of this, I did the stg release and everything just worked out of the box.
        So the takeaway would seem to be that this XML Transform tool is intended for usage on Releases and not Builds.
        For context, our current pattern is a dev build that has release steps and a stg release. I am realizing that this is not the best pattern and will work to convert my projects as I am able. 🙂

        As an aside, I can also confirm that the case does not matter for EnvironmentName, at least as far as this transform step is concerned. 🙂

        Thanks for your help. I never would have gotten this far without your article.


  3. Thanks for your article, it works fine on the root folder/main web app. But it doesn’t work at the virtual app or web job, do you have any idea about this issue?


        1. Have you considered using a slot rather than a virtual app?

          Web jobs don’t have a configuration, right? They’re just a PS script or something similar. What are you trying to transform for that?


  4. What if we’re not deploying to Azure, but to an internally hosted IIS server? Are there any extensions that would apply the transformations at release time for that? I’ve been using the WinRM IIS App Deployment task, but haven’t really been able to find anything that does the web.config transformation on the deploy without writing a custom task


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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s

Create a website or blog at

Up ↑

%d bloggers like this: