How to: Transform Web.config When Deploying a Web Application Project

When you deploy a Web site, you often want some settings in the deployed application's Web.config file to be different from the development Web.config file. For example, you might want to disable debug options and change connection strings so that they point to different databases. This topic explains how to set up a Web.config transform file that is applied automatically during deployment in order to make changes to the deployed versions of Web.config files.

Web.config transforms are part of a broader group of settings that you can configure to automate the deployment process. For information about the tasks that are involved in setting up automated deployment, see the following topics:

Note

Web deployment tools have been improved in Visual Studio 2012. You can install the improved tools in Visual Studio 2010 and Visual Web Developer 2010 Express by installing the Visual Studio Web Publish Update. For information about how to use the new tools, see the documentation for Visual Studio 2012. A good place to start is Web Application Project Deployment Overview for Visual Studio and ASP.NET.

Creating and Coding a Transform File

To specify the changes that you want to be make in Web.config files, you use transform files. A transform file is associated with a build configuration. By default, Visual Studio creates Debug and Release build configurations. You can also create custom build configurations.

To create and code a transform file

  1. If you want to create a transform file for a custom build configuration that does not exist, create the build configuration first by using Configuration Manager.

    You can open Configuration Manager by selecting it from the Build menu. For more information, see Configuration Manager Dialog Box.

  2. In Solution Explorer, expand the application Web.config file.

    If any transform files have already been created, the Web.config file is displayed in Solution Explorer with a symbol indicating that it can be expanded, and the transform files are shown when you expand the Web.config file.

    The build configuration that a transform is for is indicated by a string in the file name. For example, a transform file for the Debug build configuration is named Web.Debug.config.

  3. If no transform file exists for the build configuration that you want to specify settings for, in Solution Explorer, right-click the Web.config file and then click Add Config Transforms.

  4. Open the transform file for the build configuration that you want to work with.

  5. Edit the transform file to specify the changes that should be made to the deployed Web.config file when you deploy by using that build configuration.

    The default transform file includes comments that show how to code some common transforms.

    The following example shows how to use the Match locator and the SetAttributes transform attribute. The Match locator attribute identifies the add element in the connectionStrings section as the element to change. The SetAttributes transform attribute specifies that this element's connectionString attribute should be changed to "ReleaseSQLServer".

    <configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
      <connectionStrings>
        <add name="MyDB" 
          connectionString="ReleaseSQLServer" 
          xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
      </connectionStrings>
    </configuration>
    

    For more information about how to write transform files, see Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 1 of 4) and Web.config Transformation Syntax for Web Application Project Deployment.

  6. Save and close the transform file.

    When you deploy the Web application by using the selected build configuration and by using either a deployment package or one-click publish, the Web.config file is transformed according to your specifications.

See Also

Tasks

How to: Deploy a Web Application Project Using One-Click Publish and Web Deploy

How to: Deploy a Web Application Project Using a Web Deployment Package

Concepts

ASP.NET Deployment Content Map