Chaining Azure Web.Config Transforms When Deploying From Source Control

Visual Studio 2012 introduced chained config transforms for publish profiles. Chained transforms allow an environment-specific transformation to be applied during the deployment process in addition to the standard build transform. A typical transform chain is Web.config » Web.Debug.config » Web.Staging.config. When publishing from Visual Studio to Azure Web Sites you can take advantage of this feature to customize you configuration per environment. Unfortunately, when publishing from source control, chained transformations not supported by the Azure build and deployment process.

Fortunately, there are two things you can do to get around this limitation. The first is to up-vote this feature suggestion so the Azure team knows the feature is needed. The second is to follow the four three steps below to add the feature into the build process yourself.

Step 1: Add an environment-specific transform file

The first step is to add a new transformation file specific to your deployment environment. For these instructions, I'll assume you have one Azure Web Site for staging purposes, so add a new file named Web.Staging.config and configure the transforms you need. The naming convention of Web.Environment.config is important as you'll see in the next step.

Step 2: Add the TransformXml task to your project file

The second step is to add a single new task to your web site project file. To do this, open the project file in a text editor and scroll all the way to the bottom. You will see a commented out target named AfterBuild with a friendly note that you can uncomment the target and add tasks to it. Take this advice, uncomment the AfterBuild target and add the TransformXml task as shown:

<Target Name="AfterBuild">
    <TransformXml Condition=" '$(Environment)' != '' " Source="Web.config" Transform="Web.$(Environment).config" Destination="Web.config" />

If you're unfamiliar with MSBuild, $(Environment) refers to a property named Environment that you're going to set in the next step. The Source and Destination attributes should be obvious, while the Condition attribute ensures the task will only run when the Environment property is set.

Step 3: Add an app setting in Azure for your environment

The third step is to sign into your Azure Web Site portal and add a new app setting called SCM_BUILD_ARGS with a value of /p:Environment=Staging. This is done under the Configure page of your web site. The value specifies the Environment property that will be passed to MSBuild. Ensure the value matches the environment name of your transform file.

Configure Environment App Setting

Step 4: Customize the site build script

Thanks to Amit Apple in the comments, this step is no longer needed.

The source control build system that powers Azure Web Sites calls a simple batch file to invoke the build process. Instead of using the default batch file, you'll supply your own and pass in the Environment property.

Follow these instructions for generating the build script files you'll need. When you're done, you'll have two new files in the root of your repository, .deployment and deploy.cmd. Open deploy.cmd in a text editor and find the line that calls MSBuild.

In the list of properties passed to the build command add Environment=%ENVIRONMENT%; and save the file. This will pass the ENVIRONMENT app setting set in step three to the build process as a property named Environment, which is referenced by the TransformXml task you added in step 2. The resulting line should resemble:

... /p:Environment=%ENVIRONMENT%;_PackageTempDir="%DEPLOYMENT_TEMP%"; ...


Commit the new and updated files to your repository and you're done. The next time your project is built by the Azure Web Site build system your environment-specific Web.config transformations will be chained together.