The XML Document Transform language, or XDT, shipped with Visual Studio 2010. It’s an XML dialect designed to help you automatically transform your .NET config files appropriately for your various deployment environments.

Great. I love XML, obviously

Don’t worry, XDT is very simple and specifically designed for the task of transforming configuration files. For this scenario, it is much easier to use than a general-purpose transformation language like XSLT.

Application configuration files tend to be mostly identical across different deployment environments. Only small modifications, such as the value of your connection strings, the debug attribute, and so on, are required to create a production Web.config file out of a development Web.config file.

To show how simple it is, the basic semantics of the language can be expressed in a few lines of C#.

Let’s assume an existing Web.config file for our input document. We’ll also write a small XDT transform document which sets the ASP.NET debug attribute to false:

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
	<system.web>
		<compilation debug="false" xdt:Transform="SetAttributes" />
	</system.web>
</configuration>

Notice it looks a bit like a small Web.config document. The input doc could be a big, complex Web.config file, but that doesn’t matter – the transform doc only needs to contain the differences.

The Transform attribute is defined within a distinguished XML namespace to ensure that it can’t clash with any existing attributes in the input doc. In this case, we’re using one of the most useful built-in transforms, SetAttributes, which modifies attribute values on the targeted element to those that are specified in the transform doc – in this case, setting debug to false. There are other useful transforms, such as Remove and Replace, which alter the targeted element in different ways.

A transform implicitly specifies the element(s) in the input document to act upon by virtue of the element that it belongs to: expressed in XPath, the above transform would target the
/configuration/system.web/compilation element(s).

Here is a simple implementation of XDT using C#:

        public XDocument Transform(XDocument inputDoc, XDocument transformDoc)
        {
            var workingDoc = new XDocument(inputDoc);

            // (1) pair each "Transform" element with the element(s)
            // it targets in the working document
            var xs = from e in transformDoc.Descendants()
                     from a in e.Attributes(Namespaces.Xdt + "Transform")
                     let xpath = GetElementXPath(e)
                     select new
                     {
                         TransformElement = e,
                         TargetElements = workingDoc.XPathSelectElements(xpath)
                     };

            // (2) apply each transform to its target elements
            foreach (var x in xs)
            {
                ApplyTransform(x.TransformElement, x.TargetElements);
            }

            return workingDoc;
        }

Show me the source code

This is a slight simplification, and of course doesn’t show you the implementation of the individual transforms or how to compute the XPath. You can find the full, reasonably complete implementation of XDT on Google Code.

Locators

The implicit XPath location of, for example, a /configuration/appSettings/add element would usually specify more than one element in most Web.config files. While this is valid, it’s not very useful. XDT provides a second attribute, Locator, which allows you to augment the implicit XPath expression with a predicate to filter the target element set:

                <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
                  <appSettings>
                    <add xdt:Locator="Condition(@key='key3')" />
                  </appSettings>
                </configuration>

This would give us target XPath of /configuration/appSettings/add[@key='key3'], which is much more useful (although it doesn’t do anything, because we haven’t specified any transform!).

A convenience case of the Condition locator is to simply Match on the specified attribute, so to actually alter a particular app setting value, you would write:

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

This specifies a SetAttributes transform with the same target XPath as the previous example.

Why XDT?

• It’s part of Visual Studio 2010, and you can expect it to become the standard way of managing different config files.
• It’s really rather nice – it’s ideal for tweaking XML documents, so long as the changes aren’t big. It’s very readable (despite being XML) and quite easy for anyone to use.
• You don’t really want to use XSLT for this sort of thing.

Why write a free implementation?

I wanted to use XDT in production before Visual Studio 2010 was released. I also find that thinking about the implementation of something helps you understand its semantics. However, there are some other good reasons:

• XDT is currently restricted to web applications. Out of the box, it can’t be used with Windows or console apps, or even web “site” style projects. But this is no restriction of the language itself.
• XDT is currently restricted to Web.config files. Real applications tend to have more than one XML configuration file which needs to be transformed.
• You might not be using Visual Studio 2010.
• You might want to decouple the notions of build configuration and build environment. They’re not the same concept, but the Visual Studio 2010 designers chose to keep things simple. With several “release” environments, this conceptual simplicity comes at the cost of flexibility and creates duplication in the project and solution manifest files. A more sophisticated build system might prefer to keep just the standard two build configurations (Debug, Release) but define several deployment environments (Dev, Test, Uat, Live…), each with different config transformations.

If you’re creating a serious build system, these restrictions would otherwise probably prevent you from using XDT for your transformations, which would be a shame.

It feels like a classic Microsoft situation – a well-engineered core technology, but restricted (understandably) for commercial / shipping reasons. If you do want to go ahead and use this alternative implementation, it’s very straightforward to create an MSBuild task to call XdtTransformer.Transform() in order to use XDT in your build system. If there’s enough demand, I could add one to the distribution on Google Code.

Disclaimer The semantics of this implementation are based purely on my reading of the XDT product documentation on MSDN. The implementation passes all of the example tests I’ve found on the web – but, as usual, no warranties are implied.