Convert-XmlFile

An XDT file specifies how to change an XML file from a known beginning state into a new state. This is usually helpful when deploying IIS websites. Usually, the website's default web.config file won't work in different environments, and needs to be changed during deployment to reflect settings needed for the target environment.

XDT was designed to apply a tranformation against an XML file in a known state. Do not use this method to transform an XML file in-place. There lies madness, and you will never get that square peg into XDT's round hole. If you really want to transform in-place, you're responsible for checking if the source/destination file has already been transformed, and if it hasn't, calling Convert-XmlFile to transform to a temporary file, then copying the temporary file onto the source/destination file.

You can load custom transformations. In your XDT XML, use the xdt:Import element to import your transformations. In your XDT file:

<?xml version="1.0"?>
<root xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <!-- You can also use the "assembly" attribute (PowerShell v3 
         *only*).  In PowerShell v2, you can only use the `path` 
         attribute.

         All classes in `namespace` that inherit from the XDT 
         `Transform` class are loaded. -->
    <xdt:Import path="C:\Projects\Carbon\Lib\ExtraTransforms.dll"
                namespace="ExtraTransforms" />
    <!-- ...snip... -->
</root>

You also have to pass the path to your custom transformation assembly as a value to the TransformAssemblyPath parameter. That's it! (Note: Carbon does not ship with any extra transformations.)

When transforming a file, the XDT framework will write warnings and errors to the PowerShell error and warning stream. Informational and debug messages are written to the verbose stream (i.e. use the Verbose switch to see all the XDT log messages).