How web.config transformation simplifies web deployment

One of the most common questions that our technical support team hears is “Why does my web site work locally but not on your server?”  In most of these cases, the customer forgot to update some settings that are local to their development environment in the configuration file (for example; the database connection string).

When you deploy a web application to a production server, you often want to maintain different settings between the development and production environments.  For instance, you may want to set customError to “On” in production but leave it “Off” in development. With previous versions of Visual Studio .NET, you would have to manually edit the web.config file before you uploaded it to the server. But a cool new feature in Visual Studio .NET 2010 allows you to transform the web.config file when you deploy your application.

In this article I am going to demonstrate how to use web.config transformation to:

• Change the database connection string
• Change customError to “RemoteOnly”

Note: web.config transformation is only available in Web Application Projects.

• Open your Web Application Project in Visual Studio 2010
• In the Solution Explorer, click the “Show All Files” button
• When you expand the web.config, you should see two additional files named Web.Debug.config and Web.Release.config. These files contain the transformation rules for the Debug and Release Configuration. You can add more configurations using the Configuration Manager (Build -> Configuration Manager).

In this example we are using a very simple web.config.

<?xml version="1.0"?>
<configuration>

   <appSettings/>
   <connectionStrings>
     <add name="ConnectionString1" connectionString="Data Source=.\SQLEXPRESS;AttachDbFilename=|DataDirectory|\Database1.mdf;Integrated Security=True;User Instance=True" providerName="System.Data.SqlClient"/>
   </connectionStrings>
   <system.web>
     <compilation debug="true" strict="false" explicit="true"/>
     <authentication mode="Windows" />
     <customErrors mode="Off" />
     <pages>
       <namespaces>
         <clear />
         <add namespace="System" />
         <add namespace="System.Collections" />
         <add namespace="System.Collections.Generic" />
         <add namespace="System.Collections.Specialized" />
         <add namespace="System.Configuration" />
         <add namespace="System.Text" />
         <add namespace="System.Text.RegularExpressions" />
         <add namespace="System.Web" />
         <add namespace="System.Web.Caching" />
         <add namespace="System.Web.SessionState" />
         <add namespace="System.Web.Security" />
         <add namespace="System.Web.Profile" />
         <add namespace="System.Web.UI" />
         <add namespace="System.Web.UI.WebControls" />
         <add namespace="System.Web.UI.WebControls.WebParts" />
         <add namespace="System.Web.UI.HtmlControls" />
       </namespaces>
     </pages>
 </system.web>

</configuration>

For the sake of simplicity, I am going to use only the Release Configuration.  Technically speaking, you can have a different transformation between Debug, Release or your own custom configuration.

Transform connection string

• In the solution explorer, double click the Web.Release.Config
• Add this node to the transformation file:

<connectionStrings>
  <add name="ConnectionString1"
    connectionString="Data Source=SQL2k801.discountasp.net; Initial Catalog=DatabaseName; Integrated Security=False;User Id=SQLUserName;Password=SQLPassword"
    xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
 </connectionStrings>

This line tells the transformation engine to replace the connectionString attribute in the original web.config with another connection string.

Transform Debug mode

In general, you do not want to run your application in debug mode in a production environment for performance reasons. By default, Visual Studio .NET 2010’s transformation file already has a rule to transform the debug setting to “Off:”

<compilation xdt:Transform="RemoveAttributes(debug)" />

Transform custom error

In most production applications, you would not want your user to see the complete error when the application throws an exception.
To transform the web.config’s custom error, you would add this node:

 <customErrors mode="RemoteOnly" xdt:Transform="Replace">
   <error statusCode="404" redirect="notfound.htm"/>
 </customErrors>

This line tells the transformation engine to Replace the customErrors node with this one. The resulting Transformation file will look like this:

<?xml version="1.0"?>

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

   <connectionStrings>
     <add name="ConnectionString1"
       connectionString="Data Source=SQL2k801.discountasp.net; Initial Catalog=DatabaseName; Integrated Security=False;User Id=SQLUserName;Password=SQLPassword"
 xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
 </connectionStrings>
 <system.web>
   <compilation xdt:Transform="RemoveAttributes(debug)" />

   <customErrors mode="RemoteOnly" xdt:Transform="Replace">
     <error statusCode="404" redirect="notfound.htm"/>
   </customErrors>
 </system.web>
</configuration>

When you deploy your application now, you will see that Visual Studio .NET will change the web.config file as we have specified above. This new feature should prevent a lot of site deployment headaches.

For more information on this topic, review the following:

• http://blogs.msdn.com/webdevtools/archive/2009/05/04/web-deployment-web-config-transformation.aspx
• http://msdn.microsoft.com/en-us/library/dd465326%28VS.100%29.aspx

Frank Cheung
CTO