Web.Config Transformations made easy

G’day guys!

Who doesn’t love working with Web.Config XML files, and more specifically, the XDT Transforms that often go with them? What you’ll read next will be part-explanation, part-rant and part-tutorial on what XDTs are, why they can be bloody frustrating to work with and lastly, a suggestion from yours truly about how to alleviate some of those pain points.

I’ve heard of XML, but what the frodo are XDTs?

According to one tutorial, XDTs have been around since Visual Studio 2010, but I’ll forgive you if you’re not super familiar with them - especially if you’re not a big .NET Framework guy. They seem to be used less and less in .NET Core, where our project configuration is usually based on appsettings.json files instead of web.config files. If you’re unlucky (or lucky - depending on your POV) enough to be working on some legacy .NET Framework projects though, they are still very relevant.

XDT stands for XML Document Transform, and is a syntax and technology for - you guessed it - transforming XML files based on certain transform documents. How these are typically used is that, next to your Web.config file, you’ll also have a Web.<Configuration>.config file with some XDT syntax in it. Speaking of, if you’re just after a reference for the less-than-intuitive XDT syntax, you can find a decent sample on Microsoft Docs.

These XDT Config Transform files tell MSBuild how to transform the source Web.config file for deployment. As you might expect, these transform files are a pretty decent way to maintain different sets of configuration for different environments (eg: different connection strings between test and production databases). Out of the box, these transforms will be processed by Visual Studio whenever a web project is published. Using a Visual Studio extension called SlowCheetah, you can also get these transforms to run on build for non-web projects.

Sounds cool so far. Where’s the frustration?

Hold your optimism, Samwise. In the last two sentences lie a pretty nasty limitation of the XDT tooling that’s typically available. For web projects, the XDT transforms are only run on publish. For non-web projects, using SlowCheetah, the XDT transforms run on build (which is better), but you’d still probably want these transforms to run pre-build in either scenario, so that you can inspect the resulting config that will be used when your project is launched. This would be not only much better for local debugging, but also very helpful in verifying changes to XDTs before committing them.

Now sure, the SlowCheetah VS extension does offer a preview feature, and there are a few different online tools like this one which will show you the resulting XML after taking a source and an XDT - but you should of course be very wary of just copy-pasting your config into an online tool. Generally, what I want is to be able to run a transform locally (even offline) and have the resulting XML file be ready for me to run my project with, web or otherwise. Also, I may be using Rider or VSCode, so ideally it should not be a VS extension either.

So what do you suggest?

Here’s where I hit you with my shameless plug. I ended up writing a little tool to solve both the problem of previewing an XML Transformation, as well as running the transformation to use for local debugging. Here’s a link to the repository on Github. It comes with a cross-platform GUI tool written in AvaloniaUI (I talked a little about Avalonia here), and a cross platform command line utility that’s packaged as a dotnet tool as well. For convenience, here are some steps to install the command line program as a dotnet tool.

1. Navigate to the releases page and download XMLTransformer.Console.1.0.0.nupkg.
2. Open a terminal in the package download directory and run dotnet tool install --global --add-source ./ XMLTransformer.Console.
3. Verify that the tool was installed correctly by running xmlt --version. You should see XMLTransformer.Console 1.0.0 as the command’s output.
4. Use xmlt --help for usage instructions. But the short version of it is xmlt -i <path-to-web.config> -t <path-to-xdt-1> <path-to-xdt-2>.

That’s right, the tool supports running multiple XDT files in succession. I found this to be particularly useful for if I have one XDT file checked into source control as part of the project, and another XDT file with my user-specific or local config that’s sitting on my desktop, for example.

Anyway, I hope this tool ends up helping someone out - though I’m sure that at the very least, I’ll probably come back to this page when I need to install it myself again on a new machine.

Thanks for reading along with me so far, and catch ya next time!