Testing Web.config Transformations, Part 1

Web.config transformations is a Microsoft-supported technology for adapting a base configuration to a particular deployment environment.

In my previous post, I mentioned how AppHarbor provides an online tool for manually testing transformations. Also, the Visual Studio extension SlowCheetah provides support for manually testing and transformation and diffing them against the base configuration from inside Visual Studio. These tools are useful and may be fine for tinkering with getting a transform just right, but being software professionals, we find it highly desirable to reliably automate our transformation testing.

In this article we shall look at one way to exercise our Web.config transformations from our own code, so that we can TDD our transformations and regression test them as part of our continuous integration cycle, like everything else.

Starting Point

The actual Web.config transformation process is normally invoked by MSBuild, as described in detail by Elton Stoneman in this post. (One approach to testing the transformations could, thus, be to fork off MSBuild processes on custom build targets, but we'd like to take a less cumbersome route.)

Being an MSBuild task means that the transformation is implemented as an ITask realization. The concrete implementation is called TransformXml and resides in the Microsoft.Web.Publishing.Tasks.dll assembly. Note that this assembly is not pre-installed with Windows/.NET but rather installed along with Visual Studio 2010, typically to C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\Web). Given that its location is not fixed, you'd probably want to add it to your dependencies folder (caveat emptor: check license terms before passing it around).

From Elton's post, we can also see 3 arguments being passed to the TransformXml task:

• Source (the XML file to transform)
• Transform (the transformation XML file itself)
• Destination (the target of the transformed XML file)

Armed with that background knowledge, let's move on and try to get the transformation to run outside of the MSBuild environment in which it normally executes. For our experiment, we'll be transforming the following source (app.config):

<configuration>
  <appSettings>
    <add key="testKey" value="testValue"/>
  </appSettings>
</configuration>

The transformation we'll be testing (app.Debug.config) should change the "testValue" of the "testKey" to something transformation specific ("debugValue" in this case):

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <appSettings>
    <add key="testKey"
         value="debugValue"
         xdt:Locator="Match(key)" xdt:Transform="SetAttributes" />
  </appSettings>
</configuration>

Test Approach

Our initial stab at automatically testing the transformation will be to invoke the XmlTransform through its outermost interface; i.e. the ITask interface. First, we need to add a reference to Microsoft.Web.Publishing.Tasks.dll as mentioned above. Additionally, we need to reference Microsoft.Build.Framework and Microsoft.Build.Utilities.v4.0 (these should be available from your usual Project, Add Reference, .NET tab).

Opening up the XmlTransform class in Visual Studio's Object Browser shows us a single method, Execute(), plus a handful of properties, most of which we recognize from Stoneman's previously mentioned post. A little experimentation reveals the following details:

• SourceRootPath
• The base path to which the XML file specified in Source is relative. If not specified, this will  be the current directory (which, when running from a test runner, would typically be your build target directory).
• Source
• The name of the XML source file to be transformed. If this is not an absolute path, it will be relative to the SourceRootPath.
• TransformRootPath
• The base path to which the XML file specified in Transform is relative. If not specified, this will be the same as SourceRootPath.
• Transform
• The name of the XML transformation to be applied to the source. If this is not an absolute path, it will be relative to the TransformRootPath.
• Destination
• The name of the resulting transformed XML file. If this is not an absolute path, it will be relative to the current directory (typically your build target directory, in a test context).

So all we need to do is something like the following, right?

var transformer = new TransformXml
{
   SourceRootPath = @"..\..\..\Cumbayah.WebTransformTesting\",
   Source = @"app.config",
   Transform = @"app.Debug.config",
   Destination = @"app.transformed.config"
};
var transformationSucceeded = transformer.Execute();

Well, as the System.InvalidOperationException with the message "Task attempted to log before it was initialized" thrown in our face subtly tells us, this is not quite the case...

Investigating the task implementation with Reflector shows the problem to be due to the fact that a property, BuildEngine, of the Task base class has not been set. It is used as a dependency injection mechanism, giving the task access to some environment services (see IBuildEngine on MSDN) normally provided by MSBuild.

Well, the whole purpose of this experiment was to run outside of MSBuild, so we'll roll our own "build engine" instead:

public class BuildEngineForTest : IBuildEngine
{
   public void LogErrorEvent(BuildErrorEventArgs e)
   {
      Console.WriteLine(LogFormat, "ERROR", e.Message);
   }

   public void LogWarningEvent(BuildWarningEventArgs e)
   {
      Console.WriteLine(LogFormat, "WARNING", e.Message);
   }

   public void LogMessageEvent(BuildMessageEventArgs e)
   {
      Console.WriteLine(LogFormat, e.Importance, e.Message);
   }

   public void LogCustomEvent(CustomBuildEventArgs e)
   {
      Console.WriteLine(LogFormat, "CUSTOM", e.Message);
   }

   public bool BuildProjectFile(
      string projectFileName, string[] targetNames,
      IDictionary globalProperties, IDictionary targetOutputs)
   {
      return true;
   }

   public bool ContinueOnError
   {
      get { return true; }
   }

   public int LineNumberOfTaskNode
   {
      get { return 0; }
   }

   public int ColumnNumberOfTaskNode
   {
      get { return 0; }
   }

   public string ProjectFileOfTaskNode
   {
      get { return string.Empty; }
   }

   private const string LogFormat = "{0} : {1}";
}

This was the piece we were missing to be able to run the transformation outside MSBuild. We are, thus, able to write our coveted test:

...
   [Test]
   public void ApplyingDebugTransformationToConfigurationSetsExpectedKey()
   {
      const string targetFile = @"app.transformed.config";

      var transformer = new TransformXml
      {
         BuildEngine = new BuildEngineForTest(),
         SourceRootPath = @"..\..\..\Cumbayah.WebTransformTesting\",
         Source = @"app.config",
         Transform = @"app.Debug.config",
         Destination = targetFile
      };

      // Left as exercise for the reader... ;]
      AssertKeyInTransformedFile(targetFile);
   }
...

Our transformation runs successfully, yielding the following console output from our "build engine":

Normal : Transforming Source File: ..\..\..\Cumbayah.WebTransformTesting\app.config
Normal : Applying Transform File: ..\..\..\Cumbayah.WebTransformTesting\app.Debug.config
Low : Executing SetAttributes (transform line 6, 35)
Low : on /configuration/appSettings/add[@key='testKey']
Low : Applying to 'add' element (source line 4, 6)
Low : Set 'key' attribute
Low : Set 'value' attribute
Low : Set 2 attributes
Low : Done executing SetAttributes
Normal : Output File: app.transformed.config
Normal : Transformation succeeded

Yay? Yay.

Conclusion

We have shown how Web.config Transformations can be invoked programmatically, outside the MSBuild process by providing a simple custom IBuildEngine realization; a technique that might prove useful for other scenarios as well.

We have applied that knowledge to enable automated testing of our transformations.

In my next post in this series, we'll continue our investigation, aiming to get rid of the whole, nasty detour around the file system.

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd">
  <rules>
    <logger name="*" minlevel="Warn"
      xdt:Transform="SetAttributes(minlevel)" xdt:Locator="Match(name)"
    />
  </rules>
</nlog>

<nlog>
  <rules>
    <logger name="*" minlevel="Warn"
      xdt:Transform="SetAttributes(minlevel)" xdt:Locator="Match(name)"
    />
  </rules>
</nlog>

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform"
  xmlns:nlog="http://www.nlog-project.org/schemas/NLog.xsd"
>

  <nlog:nlog>
    <nlog:rules>
      <nlog:logger name="*" minlevel="Warn"
        xdt:Transform="SetAttributes(minlevel)" xdt:Locator="Match(name)"
      />
    </nlog:rules>
  </nlog:nlog>

</configuration>