< Back
Convert-CXmlFile
Post
NAME Convert-CXmlFile
SYNOPSIS
Transforms an XML document using XDT (XML Document Transformation).
SYNTAX
Convert-CXmlFile -Path <String> -XdtPath <String> -Destination <String> [-TransformAssemblyPath <String[]>]
[-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Convert-CXmlFile -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-CXmlFile` 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).
PARAMETERS
-Path <String>
The path of the XML file to convert.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-XdtPath <String>
The path to the XDT file.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-XdtXml <XmlDocument>
The raw XDT XML to use.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Destination <String>
The destination XML file's path.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TransformAssemblyPath <String[]>
List of assemblies to load which contain custom transforms.
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-Force [<SwitchParameter>]
Overwrite the destination file if it exists.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Convert-CXmlFile -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 --------------------------
Convert-CXmlFile -Path ".\\web.config" -XdtXml "<configuration><connectionStrings><add name=""MyConn""
xdt:Transform=""Insert"" /></connectionStrings></configuration>" -Destination '\\\\webserver\\wwwroot\\web.config'
Transforms `web.config` with the given XDT XML to a new file at `\\\\webserver\\wwwroot\\web.config`.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Convert-CXmlFile -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 --------------------------
PS C:\\>Convert-CXmlFile -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`.
RELATED LINKS
http://msdn.microsoft.com/en-us/library/dd465326.aspx
http://stackoverflow.com/questions/2915 ... sformation
Set-CDotNetConnectionString
Set-CDotNetAppSetting
SYNOPSIS
Transforms an XML document using XDT (XML Document Transformation).
SYNTAX
Convert-CXmlFile -Path <String> -XdtPath <String> -Destination <String> [-TransformAssemblyPath <String[]>]
[-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Convert-CXmlFile -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-CXmlFile` 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).
PARAMETERS
-Path <String>
The path of the XML file to convert.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-XdtPath <String>
The path to the XDT file.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-XdtXml <XmlDocument>
The raw XDT XML to use.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Destination <String>
The destination XML file's path.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TransformAssemblyPath <String[]>
List of assemblies to load which contain custom transforms.
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-Force [<SwitchParameter>]
Overwrite the destination file if it exists.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Convert-CXmlFile -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 --------------------------
Convert-CXmlFile -Path ".\\web.config" -XdtXml "<configuration><connectionStrings><add name=""MyConn""
xdt:Transform=""Insert"" /></connectionStrings></configuration>" -Destination '\\\\webserver\\wwwroot\\web.config'
Transforms `web.config` with the given XDT XML to a new file at `\\\\webserver\\wwwroot\\web.config`.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Convert-CXmlFile -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 --------------------------
PS C:\\>Convert-CXmlFile -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`.
RELATED LINKS
http://msdn.microsoft.com/en-us/library/dd465326.aspx
http://stackoverflow.com/questions/2915 ... sformation
Set-CDotNetConnectionString
Set-CDotNetAppSetting