Applying XDT magic to App.Config

For several weeks now people have been asking to be able to use the XML Document Transform (XDT) with App.Config files similar to what is available with Web.Config files in VS 2010…

In all honesty there is no official/supported  implementation of XDT for any other project type than Web Application Projects but the good news is that the basis of Web.Config Transformation resides in Web Publishing Pipeline (WPP) which are set of extensible tasks and targets hooked up to provide a great deployment story for Web Applications…

Today, Ming (our senior dev on Visual Studio) and I decided to get together to give some love to App.Config file too… The below implementation is a crude way of getting XDT working into other project types within VS 2010… In a way, I would say it is a big solution for a smaller problem but the idea here is to get people unblocked and show the kind of things that WPP is capable of doing… 

If by now everything is sounding foreign then please check out the articles:

Web.Config Transformation

VS 2010 Snippets for Web.Config Transformations

Web.Config Transforms (XDTs) for any XML files in your web projects

Goals

• Being able to use XDT syntax for App.Config files similar to what you can use with Web.Debug.Config and Web.Release.Config…
• Being able to use this in an automated fashion in build environments like Team Build…
• Reduce the concept count and make it as simple as possible (without digging deep into optimization & performance)…

Step by Step Instructions

The example I am using below should be hopefully super simple that you can follow along without any prep work… All you need is VS 2010 which has “Visual Web Developer” components installed…

Step 1 Create a new Windows Forms Application in VS 2010

Step 2 Add App.Config file to the project…

Add simple test settings to App.Config file as shown below:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="author" value="Vishal Joshi"/>    
  </appSettings>
</configuration>

Step 3 Add App.Debug.Config file to the project, I would recommend using the same App.Config file adding mechanism as shown below

Step 4 Modify the content of App.Debug.Config as shown below:

<?xml version="1.0"?>

<!-- For more information on using App.config transformation visit http://go.microsoft.com/fwlink/?LinkId=125889 -->

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <appSettings>
    <add key="article" value="XDT Magic for App.Config Files" xdt:Transform="Insert"/>
  </appSettings>
</configuration>

The key things to note above are:

• There is a XDT namespace declaration which allows XDT engine to recognize the Transform/Locator syntax in the file



• There is a new node being inserted into the config file using the syntax xdt:Transform=”Insert”

Step 5 Save the edited files and unload the project frin VS 2010 Solution Explorer using the right click command as shown below:

Step 6 Edit the .csproj/.vbproj file to make App.Debug.Config file to be dependent on App.Config file as shown in the syntax below:

    <Content Include="App.config" />
    <Content Include="App.Debug.Config" >
      <DependentUpon>App.Config</DependentUpon>
    </Content>

The key things to note above are:

• By default the build action of App.Config and App.Debug.Config file will be “ None”… It needs to be changed to “Content”… This is a tiny pre-requisite for WPP but if you encounter any issues because of this then we can dig the work around…



• DependentUpon node will make your App.Debug.Config appear as a node under your App.Config file similar to the way Web.Debug.Config and Web.Release.Config files appear under Web.Config file…



• In VB Projects nested files are hidden so you might need to unhide these by clicking the icon on the solution explorer…

Step 7 Change the ProjectConfigFileName property within your .csproj/.vbproj file

WPP has an inbuilt property called ProjectConfigFileName which is by default set to Web.Config, we need to change this to app.Config which will allow projects like WinForm project not expect web.config files to transform… You can add this property right under ProjectGuid property as shown below:

  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <ProductVersion>8.0.30703</ProductVersion>
    <SchemaVersion>2.0</SchemaVersion>
    <ProjectGuid>{2D587604-866B-4675-8587-FA9728EC59D8}</ProjectGuid>
    <ProjectConfigFileName>App.Config</ProjectConfigFileName>

Step 8 Hook up WPP within your WinForms project by importing the WPP targets.

You can search for “Import” node in your project file and then simply copy below one line for WPP targets import

  <Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.targets" />

Step 9 Add a target to copy the transformed App.Config file to your output (BIN) directory

You can simply copy paste the below code just before your </project> node closes in the .csproj/.vbproj file

  <Target Name="PostTransformAppConfig" AfterTargets="TransformWebConfig">
    <Copy Condition="Exists('$(TransformWebConfigIntermediateLocation)\transformed\App.config')" 
          SourceFiles="$(TransformWebConfigIntermediateLocation)\transformed\App.config" 
          DestinationFiles="$(OutputPath)\WinFormConfigTransform.exe.config" />
    <Copy Condition="Exists('$(TransformWebConfigIntermediateLocation)\transformed\App.config')" 
          SourceFiles="$(TransformWebConfigIntermediateLocation)\transformed\App.config" 
          DestinationFiles="$(OutputPath)\WinFormConfigTransform.vshost.exe.config" />
  </Target>

The key things to note above are:

• We hooked up the new PostTransformAppConfig target after TransformWebConfig target… The TransformWebConfig target is the native target in WPP which does any XML transform and will do the actual job of transforming App.Config as well..



• The location at which the new App.Config file is getting copied is pretty self explanatory but do note that you do want to change “WinFormConfigTransform” to be the name of your own Project…  I just used a project called “WinFormConfigTransform” and hence the DestinationFiles path is named as such…

Step 10 Run /T:TransformWebConfig task on your Project from MSBuild

You need to use Visual Studio 2010 Command prompt and type in the below command

msbuild C:\Vishal\WinFormConfigTransform.csproj /t:TransformWebConfig

After running the above command if you now check the BIN folder of your project you should see that the Project.exe.Config file is now modified as shown below:

 

NOTE: If you want the App.Config file to be Transformed after every build in your Visual Studio IDE (this will take some perf away but may not even be noticeable) then you can change Step 9 code to be as below:

<Target Name="PostTransformAppConfig" AfterTargets="Build">
    <CallTarget Targets="TransformWebConfig"/>
    <Copy Condition="Exists('$(TransformWebConfigIntermediateLocation)\transformed\App.config')" 
          SourceFiles="$(TransformWebConfigIntermediateLocation)\transformed\App.config" 
          DestinationFiles="$(OutputPath)\WinFormConfigTransform.exe.config" />
    <Copy Condition="Exists('$(TransformWebConfigIntermediateLocation)\transformed\App.config')" 
          SourceFiles="$(TransformWebConfigIntermediateLocation)\transformed\App.config" 
          DestinationFiles="$(OutputPath)\WinFormConfigTransform.vshost.exe.config" />
  </Target>

The only key difference above is that I made the new target to be called after “Build” and in the new target I made a call to “TransformWebConfig” target to ensure the transform happens before we try to copy the transformed app.config file to their final location…

With the above change now when you build in IDE then the new transformed App.Config will be copied to your output directory…

With the above 10 steps you should now be able to Transform your App.config just like the way you do Web.Config files in VS 2010

-Vishal

PS:  Whenever you make changes to your project file (like above) you make your project susceptible to data loss during upgrade to future versions of VS as next versions of VS will not know all the fancy code you put in the files, but such risks are part of the game to get all the fancy toys working :-)