Friday, June 18, 2010

Parameterization vs. Web.Config Transformation

I was recently asked about being able to change values of different variables like ConnectionStrings, Installation physical directory, app Settings etc during install time rather than build time, so I thought it might be worth while to de-mystify the concepts around Web.Config Transforms and Parameterization…

Web.Config Transformation

Geeks say Web.Config Transformation is a great feature of Web Deploy (aka MsDeploy), well the first part about being a great feature is true :-) but it is important to note that Web.Config Transformation is not a Web Deploy feature but it instead is a VS 2010 only feature.  Web.Config Transformation is connected with Build configuration of MSBuild/VS/Team Build etc…  Its XML transformation engine is wrapped in MSBuild and has a UI around in VS 2010 which yeilds following benefits:

If you are building a deployment web package (.zip) and know which environment you are building for then web.config transformation is great.  This is the category where many of us fall coz we build for a release environment and need the right config file to go in that deployment package.  For that matter many people are just fine creating web packages for the correct environment they are deploying to…

Now for others who want to be able to build just once and deploy to both test as well as staging/release environment then an embedded web.config file for one environment may not work.  For this scenario there is parameterization.


Parameterization, unlike Web.Config Transform is Web Deploy (aka MsDeploy) only feature, which means that it will not work in non-Web projects or when you are using other protocols like FTP/FTPS etc.  Parameterization from Web Deploy standpoint is a 2 step process

  1. Declare Parameters: You create a Parameters.xml file and pass it to Web Deploy while creating the package…  In this file you need to indicate what file you want to parameterize  (e.g. web.config), what variable inside the file needs to be parameterized (e.g. connectionString) and what would be the default value of the variable (e.g. release connectionString)… Using Parameters.xml file, Web Deploy will create an internal meta data file within your .zip package which guides Web Deploy to know what “Questions” to ask the person who is installing the .zip package… 
  2. Set Parameters: When user is about to install the web package the value of the Parameters can be provided to Web Deploy via several means.  In case you are using IIS Manager to install the package then the IIS Manager UI will automatically show the Parameters with filled in default values.  If you are using Web Deploy command line to install the package then you can provide a setParameters.xml file to the commandline (in case of VS 2010 generated deploy.cmd file just having setParameters.xml file in same folder as the .cmd and .zip file is sufficient).  The setParameters.xml file is a very simple name-value pair file in which you can provide the value of the parameter adjacent to its name.

In one of the future posts I will write more about how to use Parameterization for some canonical deployment scenarios, but hopefully this will lay the foundation of how to differentiate between build time transforms from install time parameters.


If you can know your environment settings during build time use Web.Config transformation. 

If you would want to create deployment package only once and then enter the settings during install time then use Parameters.xml

VS 2010 actually uses a combination of Parameters and Web.Config transforms to provide you with a seamless experience (i.e. connectionStrings, IIS Application Name etc are already parameterized by default) so for most common scenarios you would hopefully not have to delve into understanding all the details but if you have any questions then of course feel free to ask here or via email…




Mark said...

Vary helpful, thanks.
Q: Can we skip folders/files during VS2010 Deploy the way we can with MSDeploy in IIS7 deployments?
For example, list a folder in the web.config

Vishal R Joshi said...

Hey Mark check out the post on excluding files & folders in Web Deployment at

Anonymous said...

Thanks for clarifying

Anonymous said...

Hi Vishal. Via email? U mean your Vishal_Joshi *at* ? I think i tried that a few weeks ago and that didn't work....

Vishal R Joshi said...


Jaans said...

Doesn't work for a .NET Setup Project. It simply uses the untransformed web.config when it installs.

Vishal R Joshi said...

Hi Jaans,
Yes it is true that tranformation does not work with .NET Setup project... Also currently there is no official plan to provide that support but I am sure community can build a custom action for the same...

Mike said...

Hi Vishal, I've asked a couple of question on stackoverflow it would be great if you could look at it... basically, is it possible include conditions in the deployment, like;
1. create this folder and add these files, if the folder doesn't already exist
2. only deploy this named folder that matches the parameter value.
Full question here...

Unknown said...

Hi Vishal
From Mike's question above, when doing parameterization and/or transformation, is it possible to do full file replacement rather than just replacement of specified keys? As Mike asked above, we have a case where we have the set config files that we want on our prod environments (because its a CMS, we need to have different sets of config per box). We have the config file for a type of box and another config file for another type of box. Is this possible with Web Deploy?

Vishal R Joshi said...

If you put xdt:Transform="Replace" on the topmost node of your web.config file then entire file will get replaced as part of web.config transformation. Would that satisfy your needs?

Vishal R Joshi said...

Mike for some reason I missed your comment. Can you send me an email at and I will connect you with the team to follow up on how to solve these issues.
Sorry again for the delay, it was unintentional.

Ivan said...

Vishal is it possible in the web.config transformations to have AppSettings change the default value in the Parameters.xml or maybe better said the resulting SetParameter.xml?

This is how it is with connectionstrings. I just want the default value to be changed in the Parameters.xml file to be environmentally specific?


Ivan Perez

Derek Greer said...

When installing via IIS, I'd like for the zip file to specify the the default web site as "" rather than the default of [MyApp].Web_deploy. I've tried several different approaches, but I can't seem to figure out how to override this setting. Currently I have this in my Parameters.xml file contained in the root of my Web project:

<?xml version="1.0" encoding="utf-8" ?>
<setParameter name="IIS Web Application Name" defaultValue="" />

Shouldn't this override the defaults?

Vishal R Joshi said...

Hi Derek,
If I understand correctly you are trying to take an web app from Visual Studio and trying to deploy it to the root of your web site ie. something like "Default Web Site/" rather than "Default Web Site/MyApp-Web_deploy".
If my assumption is correct then you should be able to simply state "Default Web Site/"and it should work. Is that not working?

Unknown said...

We have come across a problem where we cannot update an xml file which has namespace.


< />

By using below in the parameters.xml file and set the values using setparameters.xml .

The above one works if we remove the xmlns and it does not work with it. Any idea or suggestions?

Vishal R Joshi said...

Hi Manimaran,
The XML comments are stripped by bloggers but for web.*.config we had an bug around XML namespaces which was fixed in VS 2010 SP1. Can you upgrade to that.
For parameters.xml if you are facing problems with namespaces can you send me an email at and I can forward it to someone in the team to look at.

SABARI said...

Hi Vishal,
Can i add a new key to the web.config with out dropping the config file in the destination folder becoz i am already having web.config which i need to update.