Preview a Web.config Transformation

Note: This guide applies to legacy ASP.NET Framework applications that use Web.config. ASP.NET Core projects use appsettings.json and environment-based configuration, which follow a different transformation approach.

Resource: ASP.NET Web Deployment using Visual Studio: Web.config File Transformations

Ah, the good ol Web.config. If you're like me, you're very familiar with this, it's the primary configuration source for many legacy .NET Framework web applications. This holds your connection strings to services like databases, integrated service endpoints, and even custom configurations for libraries imported via NuGet.

It's not uncommon that you'd want to change your configurations right before deployment to environments that aren't your own local machine. How is this done? Thankfully it's quite the easy task for CI/CD to handle, and can be dictated as part of your web application publish step. Check out the resource I have linked for further information. This doc is focused on ASP.NET Framework Web.config transforms using the standard Web.Debug.config and Web.Release.config files, and is still highly relevant in 2025 for enterprise projects.

But, what if you want to preview this transformation without publishing your work first?

Well that's where the following technique may be useful.

A quick note about Visual Studio’s built-in Preview

Some project types in Visual Studio allow you to right-click a transform file (for example Web.Release.config) and choose Preview Transform. This is handy when available, but not every project type supports it. Also, this preview feature is limited to the IDE.

The technique below works outside Visual Studio as well, which makes it ideal for:

• Projects that do not support Preview in the IDE
• Running transforms from a build server or CI/CD pipeline
• Lightweight testing without opening Visual Studio

Setup: transform.proj

Add the following file to your project (naming it transform.proj for example):

<Project ToolsVersion="4.0" DefaultTargets="PreviewConfig" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <UsingTask TaskName="TransformXml" 
             AssemblyFile="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\Current\Web\Microsoft.Web.Publishing.Tasks.dll" />

  <Target Name="PreviewConfig">
    <!-- Transform for Staging -->
    <TransformXml Source="Web.config"
                  Transform="Web.Staging.config"
                  Destination="Preview_Staging.config" />
    
    <!-- Transform for Production -->
    <TransformXml Source="Web.config"
                  Transform="Web.Prod.config"
                  Destination="Preview_Prod.config" />
  </Target>
</Project>

Tip: If your Visual Studio installation does not contain a Current folder, change Current in the path to v17.0, or locate the folder under $(MSBuildExtensionsPath)\Microsoft\VisualStudio\ that contains Microsoft.Web.Publishing.Tasks.dll.

Running the Preview

1. Open a Developer Command Prompt for Visual Studio

2. Navigate to the project root where transform.proj is located

3. Run:

   msbuild transform.proj /t:PreviewConfig

4. This will output two transformed config files:

   • Preview_Staging.config
   • Preview_Prod.config

You can open these files next to your base Web.config to see exactly what the publish process will produce.

Why This Works

This works because:

• You are calling the same transformation engine Visual Studio uses
• The Current path ensures it works with the latest VS install without hardcoding v17.0
• The transformation runs in isolation, so there is no build, publish, or deployment required

It is fast, predictable, and matches what CI/CD will create.

Wrap Up

Previewing transforms locally can save time and avoid unnecessary publish cycles. It is a quick win for developers working with Web.config setups in multiple environments.

For more details on the transformation process, check out: 🔗 ASP.NET Web Deployment using Visual Studio: Web.config File Transformations

This technique is evergreen because the TransformXml MSBuild task has remained unchanged for years and continues to work with the latest Visual Studio builds.