Convert-XmlFile

Transforms an XML document using XDT (XML Document Transformation).

Syntax

Convert-XmlFile -Path <String> -XdtPath <String> -Destination <String> [-TransformAssemblyPath <String[]>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Convert-XmlFile -Path <String> -XdtXml <XmlDocument> -Destination <String> [-TransformAssemblyPath <String[]>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

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

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Path String

The path of the XML file to convert.

true false
XdtPath String

The path to the XDT file.

true false
XdtXml XmlDocument

The raw XDT XML to use.

true false
Destination String

The destination XML file's path.

true false
TransformAssemblyPath String[]

List of assemblies to load which contain custom transforms.

false false @()
Force SwitchParameter

Overwrite the destination file if it exists.

false false False
WhatIf SwitchParameter false false
Confirm SwitchParameter false false
CommonParameters This cmdlet supports common parameters. For more information type
Get-Help about_CommonParameters.

EXAMPLE 1

Convert-XmlFile -Path ".\web.config" -XdtPath ".\web.debug.config" -Destination '\\webserver\wwwroot\web.config'

Transforms web.config with the XDT in web.debug.config to a new file at \\webserver\wwwroot\web.config.

EXAMPLE 2

" -Destination '\\webserver\wwwroot\web.config'

Transforms web.config with the given XDT XML to a new file at \\webserver\wwwroot\web.config.

EXAMPLE 3

Convert-XmlFile -Path ".\web.config" -XdtPath ".\web.debug.config" -Destination '\\webserver\wwwroot\web.config' -Verbose

See that Verbose switch? It will show informational/debug messages written by the XDT framework. Very helpful in debugging what XDT framework is doing.

EXAMPLE 4

Convert-XmlFile -Path ".\web.config" -XdtPath ".\web.debug.config" -Destination '\\webserver\wwwroot\web.config' -TransformAssemblyPath C:\Projects\CustomTransforms.dll

Shows how to reference a custom transformation assembly. It should also be loaded in your XDT file via the xdt:Import.