ASP.NET Web Projects: web.debug.config & web.release.config

ASP.NET Web Projects: web.debug.config & web.release.config

DIsclaimer: You may experience some in-consistent behavior using this technique. If so please let us know.

I have heard a lot of questions and confusion regarding web.debug.config and web.release.config. For example here is just one question on StackOverflow. The question states:

Hello, I want to use the web.config transformation that works fine for publish also for debugging.

When i publish a web app, visual studio automatically transforms the web.config based on my

 

First let me explain, as I did to that question, the purpose of the files: web.config/web.debug.config/web.release.config.

web.config

This is the config file which developers should use locally. Ideally you should get this to be standardized. For instance you could use localhost for DB strings, and what not. You should strive for this to work on dev machines without changes.

web.debug.config

This is the transform that is applied when you publish your application to the development staging environment. This would make changes to the web.config which are required for the target environment.

web.release.config

This is the transform that is applied when you publish your application to the “production” environment. Obviously you’ll have to be careful with passwords depending on your application/team.

The problem with transforming the web.config that you are currently running is that a transform can perform destructive actions to the web.config. For example it may delete a attributes, delete elements, etc.

Resolution

Ok, with that out the way not let’s see how we can enable what the question asker wants to do. To recap, when he builds on a particular configuration he wants a specific transform to be applied to web.config. So obviously you do not want to maintain a web.config file, because it is going to be overwritten. So what we need to do is to create a new file web.template.config, which is just a copy of web.config. Then just delete web.config by using Windows Explorer (don’t delete using Visual Studio because we do not want to delete it from the project). Note: If you are using a source control provider which is integrated into Visual Studio then you probably want to delete web.config from source control. Also with this we do not want to use web.debug.config or web.release.config because these already have a well defined role in the Web Publishing Pipeline so we do not want to disturb that. So instead we will create two new files, in the same folder as the project and web.template.config, web.dev.debug.config and web.dev.release.config. The ideas is that these will be the transforms applied when you debug, or run, your application from Visual Studio. Now we need to hook into the build/package/publish process to get this all wired up. With Web Application Projects (WAP) there is an extensibility point that you can create a project file in the same folder with the name {ProjectName}.wpp.targets where {ProjectName} is the name of the project. If this file is on disk in the same folder as the WAP then it will automatically be imported into the project file. So I have created this file. And I have placed the following content:

<?xml version=“1.0“ encoding=“utf-8“?>

<Project ToolsVersion=“4.0“ xmlns=“http://schemas.microsoft.com/developer/msbuild/2003“>

 

  <!– Make sure web.config will be there even for package/publish –>

  <Target Name=“CopyWebTemplateConfig“ BeforeTargets=“Build“>

    <Copy SourceFiles=“web.template.config“

          DestinationFiles=“web.config“/>

  </Target>

 

  <PropertyGroup>

    <PrepareForRunDependsOn>

      $(PrepareForRunDependsOn);

      UpdateWebConfigBeforeRun;

    </PrepareForRunDependsOn>

  </PropertyGroup>

 

  <!– This target will run right before you run your app in Visual Studio –>

  <Target Name=“UpdateWebConfigBeforeRun“>

    <Message Text=“Configuration: $(Configuration): web.dev.$(Configuration).config“/>

    <TransformXml Source=“web.template.config“

              Transform=“web.dev.$(Configuration).config“

              Destination=“web.config“ />

  </Target>

 

  <!– Exclude the config template files from the created package –>

  <Target Name=“ExcludeCustomConfigTransformFiles“ BeforeTargets=“ExcludeFilesFromPackage“>

    <ItemGroup>

      <ExcludeFromPackageFiles Include=“web.template.config;web.dev.*.config“/>

    </ItemGroup>

    <Message Text=“ExcludeFromPackageFiles: @(ExcludeFromPackageFiles)“ Importance=“high“/>

  </Target>

</Project>

 

Let me explain this a bit. I have created the CopyWebTemplateConfig target which will always copy web.template.config to web.config on build, even if you are not debugging your application in Visual Studio. This is needed because we still need to support the package/publish process of Visual Studio. Then I extended the property PrepareForRunDependsOn to include the UpdateWebConfigBeforeRun target. This property is used to identify the list of targets which needs to be executed before any managed project is run from Visual Studio. In this target I am using the TransformXml task to transform web.template.config, using the correct web.dev.***.config file. After that your app starts up using the correct web.config based on  your build configuration.

After that I have another target ExcludeCustomConfigTransformsFiles, which I inject into the package/publish process via the attribute BeforeTargets=”ExcludeFilesFromPackage”. This is needed because we do not want these files to be included when the application is packaged or published.

So that is really all there is to it. To explain the package/publish process a bit more for this scenario. When you package/publish web.debug.config or web.release.config, depending on build configuration, will still be used. But ultimately the file that it is transforming is web.template.config, so you may have to adjust depending on what you have in that file. Questions/Comments? If you use this please let us know what you think.

Sayed Ibrahim Hashimi – @sayedihashimi

Note: Cross posted at http://sedodream.com/2010/10/21/ASPNETWebProjectsWebdebugconfigWebreleaseconfig.aspx