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 = @"..\..\..\Jayway.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 = @"..\..\..\Jayway.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: ..\..\..\Jayway.WebTransformTesting\app.config
Normal : Applying Transform File: ..\..\..\Jayway.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.

I was adding a transformation to adapt our NLog configuration for the various environments, when I ran into a problem. I'd added the following transformation, intended to set the log level to Warning on the given deloyment:

<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>

However, the original fragment kept being passed through without modification. I tried various modes of matching (incidentally, the online Web Config Transformation Tester is a good tool for such tinkering with transformations) to no avail, until I decided to try and remove the NLog namespace from the transformation:

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

And lo and behold; it worked.

That could have been the end of it, but I decided to dig a bit deeper, since we have the NLog schema in our solution and properly referencing it allows us to have IntelliSense within the web.config.

Eventually, as an experiment, I tried associating a namespace prefix with the NLog namespace at the top level, and then explicitly qualify the NLog elements with that prefix, rather than relying on specifying a default namespace on the NLog element:

<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>

Success!

Conclusion

Explicitly prefixing elements from foreign XML namespaces in config transformations must be described as a workaround, since semantically the first and the third NLog fragments are equivalent.

In spite of this flaw in the web.config transformations implementation, this workaround allows you to get the benefits of IntelliSense and better validation when you have the schema for NLog or any other foreign fragment available.

Scroll passed the background and rationale musings for the good stuff. ;~)

Background and rationale musings

Looking at a great initiative; the Common Service Locator and using it because it’s a good design practice to use abstractions one can’t help but to hunger for more! There was one more piece I felt myself wanting to sink my teeth into. After some testing, re-working and re-factoring and re-re-factoring ;~) an embryo for a common simple API begun to emerge. We have found in our team that there is a smallish set of classic configuration tasks involved in setting up your IoC:

• Register Instance (with or without a key)
• Register Type (with or without a key)
• Marking a registration a Singleton
• Selecting a constructor for injection
• Selecting properties for injection

This is it really!

Really? Yes pretty much. This is likely to fill about 95% of the needs for configuring an IoC.

We’ve tested it in our project and it works really well. We started out using the API of the IoC we chose but felt it imposed a lot of presence in our code making our coders have to know and care a lot about how and what makes the underlying container tick. All they wanted to do was configure how their code would fit together.

That seems quite easy to create and API for. Indeed. ;~)

But wait; one single API can’t possibly fulfill all of the IoC configuration needs out there for ever! True that - it can’t pretend to be a silver bullet. Well let’s make it easy to extend then.

Hmmm... If not all IoC can implement this API; wouldn’t that make the API a little pointless? Well, not really. The API would not be intended to allow you to replace one container with another without changing or even recompiling the code. Though it could be used that way. Just because you can replace one IoC with another doesn’t mean you will! Having a fitting simplification for an API – and adapter if you will – still makes a lot of sense to your code maintainability!

What if all of the existing IoC creators out there couldn’t care less about this little pesky API? Well I sure can’t blame them who has time to read each and every blog post. Fortunately it doesn’t matter. Let’s make it so that anyone who implements the API for their favorite IoC container and contribute.

That sound’s fair! Not all IoC’s might even have a configuration API for that matter and the ones that do certainly do not have to have one that is suitable for such an API we’re talking of. Besides those that like code abstractions over hard references would use the API because it makes good design sense. Those who don’t care about such things would not use the API.

OK – I’m still interested; let’s have a closer look.

Features we like

What kind of features would we like to have in our API?

• It is annoying when configuration code breaks when you refactor. Type safety?
• It would be nice if it was easy to use and that means easy to read. A fluent interface?
• If I need to add my own favorite feature it should be easy to do so. Open source with an easily extensible API?
• It should be easy to implement for your own IoC. Good use of a base class implementation?

Sample code

It’s time to look at some sample code for this thing! There is more sample code on the project site and also a listing of the API in full.

This is what the code would look like when you use the API to configure your code; easy to understand, fluent, type safe!

ServiceConfigurator.RegisterType<IFoo, Foo>()
                   .InjectionConstructor(() => new Foo())
                   .InjectionProperties(f => f.Bar, f => f.Baz)
                   .AsSingleton();

That looks just awesome! Yes indeed! Awesome and quite useful. It’s easy to see how this may be extended for specific purposes. (Doh – sorry I’ll try not to sound like a TV chef or a TV advertisement any more – sorry.)

The code above tells your IoC container that you want to register the implementation Foo as the target for requests for instances of the contract IFoo. It will tell the IoC container to use the parameterless constructor (it can use any constructor). It will also tell the IoC container to use the properties Bar and Baz for Dependency Injection. Finally it will tell the IoC container to treat the instance of Foo as a singleton instance once it is created.

The lambdas look messy! Do they? We don’t even notice any more in our project. They are there to ensure type safety and if you implement this API using the base class the expressions that make up this “mess” are parsed once and for all and converted into more easily handled parameters such as types and strings. If you change any of your configured classes and try to compile the configuration code it will not even compile.

The what and the where

If you feel this API would be pretty darn useful and nice to get your hands on you’re in luck! It’s already created and published under open source license on CodePlex.

So without further ado… Introducing

The Common Service Manager

All the information you need about this project is up there on the site so this post does not need to go any further. If you hurry YOU can contribute with the implementation for your favorite IoC and claim the fame!

If you feel this project is missing one key feature please don’t hesitate to provide feedback!

Final words

Thanks to the great guys of coding for the inspirational Common Service Locator project that set our team off in the direction to create a piece of code that extends your work. Together these two pieces of API make our every day much more easy and that is what code by developers and for developers is all about! (The title of this post is a paraphrase from Jeremy Millers classic post.)

Cheers,

M.

I've used Commons HttpClient in older versions on several occasions in the past and have found it to be extremely useful. I've only just started working with the new version, but there seems to quite a lot of good stuff in there. For example I'm thrilled to see that the Template pattern, heavily used in Spring, has now made its way to the Apache world (e.g. ResponseHandler, a callback interface to be used with HttpClient for handling results).

Now, configuration of HttpClient has always been a little bit tricky. There are so many features in there, and most of these are configured using generic parameters (HttpParams), basically name-value pairs of a setting identifier and its value. This has not been made that much easier in the new version.

In my current project I was struggling to find the appropriate parameters for configuring timeouts with the new version of the framework. It turned out to be quite difficult to find clear information on this - the documentation on the 4.0 version of HttpClient is still quite sparse. Since it took me a while to find out how to do this I figured I wasn't alone, so here goes:

My original solution for this problem - being completely unable to find the proper way to do it - was to use the hard-coded property values and set them as parameters in HttpParams. Fortunately, a reader with signature 'BoD' (see below) knew the right way to do this and was kind enough to share.

Right, the code looks as follows:

 
DefaultHttpClient httpClient = new DefaultHttpClient();
HttpParams params = httpClient.getParams();
HttpConnectionParams.setConnectionTimeout(httpParams, connectionTimeoutMillis);
HttpConnectionParams.setSoTimeout(httpParams, socketTimeoutMillis);
 

Simple as that - hard to understand why that should take me so long to figure out . Thanks again to 'BoD' for setting me straight on this.