Click here to Skip to main content
15,877,967 members
Articles / Web.config

Web.Config Transforms: A Beginner's Guide

Rate me:
Please Sign up or sign in to vote.
4.40/5 (11 votes)
18 Oct 2016CPOL3 min read 16.7K   10   2
Web.Config Transforms: A Beginner's Guide

I wanted to do this post to cover a topic a lot of people ask me about, and that's Web.Config transforms. And I wanted to provide a blog post to describe this for those who are new to the topic.

Web.config transforms are a basic building block of change management and DevOps in the sense that every application has configuration settings that need to be changed for each environment and the web.config is a common "dumping ground" for these settings.

Now I'm not saying this is not a good idea, and the web.config is fine. But honestly, I've seen too many shops that manage changes by saying "Don't replace the web.config" or maintain separate copies. This is a fine approach provided you aren't automating your deployments. If you are, then you really want to make your web.configs changes with the environment and limit access to production.

So how do we add transforms, many newer projects are pre-configured to transforms and you can tell this by looking for the following in your project.


In the image above, under the Web.config is the "Web.Debug.config" and "Web.Release.config". These are the transforms for the project, and depending on if you select "Debug" or "Release" determines which transform is applied to the web.config.

Configuration Manager

If you don't see the transforms, and you are running a Web Application, right-click on the web.config and click on "Add Config Transform".

Add transforms

Now an important part to understand is what a transform is, and what it is not.

  • IT IS => a way of managing configuration changes
  • IT IS NOT => a separate copy of the web.config

The idea is that the web.config transforms are each a delta file, they contain only the changes and use special attributes to identify and make changes.

If you open the "Web.Release.Config", you will see the following.

Release Transforms

Notice that it does not have all the attributes of the web.config, instead here if you look at the comments, it describes putting in the values that you want to change. So to start with, let's put in a connection string, the most common application change.

Connection String

So far, it looks like a pretty basic connection string entry (except for the token "_ DefaultConnection _". But so far, the entry doesn't look any different. The key difference is the attributes we add after. These are the locator and the transform as shown below:

xdt tags

The key attributes are:

  • xdt:Locator: is leveraged to find the tag within the web.config
  • xdt:Transform: is the method of changing this tag, normally "Replace"

The first attribute being "xdt:Locator", which is leveraged for it to find the tag. This is shown below:


The string in here tells it to find a "Match(name)" which translates to "Match" by the "name" attribute.

The second attribute is "xdt:Transform" which tells it to replace the entire tag:


After you've implemented this, when we publish in release mode, I get the following for my web.config:

final web.config

Now the use of the token here is so that release management can replace these tokens. For more details, look at Total ALM.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Software Developer (Senior)
United States United States
My name is Kevin Mack, I'm a software developer in the Harrisburg Area. I have been a software developer since 2005, and in that time have worked on a large variety of projects. Everything from small applications, to mobile and Enterprise solutions. I love technology and enjoy my work and am always looking to learn something new. In my spare time I love spending time with my family, and learning new ways to leverage technology to make people's lives better. If you ask me what I do, I'll probably tell you I can paid to solve problems all-day-every-day.

Check out my blog at and

Comments and Discussions

GeneralMy vote of 5 Pin
Farhad Reza17-Nov-16 5:19
Farhad Reza17-Nov-16 5:19 
GeneralRe: My vote of 5 Pin
Kevin Mack18-Nov-16 15:25
Kevin Mack18-Nov-16 15:25 
Glad you found it helpful!

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.