Convert To-Clixml

Module:
Microsoft.PowerShell.Utility
Converts objects to an XML-based representation and returns that as a string.

Syntax 

ConvertTo-Clixml
         [-Depth <Int32>]
         -InputObject <PSObject>
         [-Encoding <String>]
         [<CommonParameters>]

Description

The ConvertTo-CliXml cmdlet creates XML-based representations of objects and returns them as strings. You can then use the ConvertFrom-Clixml cmdlet to re-create the saved objects based on the contents of the strings.

A valuable use of ConvertTo-CliXml is to serialize credentials and secure strings securely as XML. For an example of how to do this, see Example 3.

Examples

Example 1: Convert a string to an XML representation 

"This is a test" | ConvertTo-Clixml

This command returns a string with am XML-based representation of the string object with a value of "This is a test".

Example 2: Convert an object to an XML-based representation 

$FileaclString = Get-Acl C:\test.txt | ConvertTo-Clixml

Fileacl = ConvertFrom-Clixml $FileaclString

This example shows how to convert an object to an XML string and then create an object by converting the XML from the string.

The first command uses the Get-Acl cmdlet to get the security descriptor of the Test.txt file. It uses a pipeline operator to pass the security descriptor to ConvertTo-Clixml , which converts the object to an XML-based representation and returns that as a string. Then, it saves the string in the $FileAclString variable.

The second command uses the ConvertFrom-Clixml cmdlet to create an object from the XML in the $FileAclString variable. Then, it saves the object in the $FileAcl variable.

Example 3: Convert an encrypted credential object 

$CredXml = $Credential | ConvertTo-Clixml

$Credential = ConvertFrom-CliXml $CredXml

The ConvertTo-CliXml cmdlet encrypts credential objects by using the Windows Data Protection API . This ensures that only your user account can decrypt the contents of the credential object.

In this example, given a credential that you've stored in the $Credential variable by running the Get-Credential cmdlet, you can run the ConvertTo-CliXml cmdlet to serialize the credential to a string.

To deserialize the credential later, run the second command. This time, you are running ConvertFrom-Clixml to import the secured credential object into your script. This eliminates the risk of exposing plain-text passwords in your script.

Required Parameters

-InputObject

Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-Clixml .

Type: PSObject
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

Optional Parameters

-Depth

Specifies how many levels of contained objects are included in the XML representation. The default value is 2.

The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.

Type: Int32
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Encoding

Specifies the type of encoding for the target file. The acceptable values for this parameter are:

  • ASCII
  • UTF8
  • UTF7
  • UTF32
  • Unicode
  • BigEndianUnicode
  • Default
  • OEM

The default value is Unicode.

Type: String
Parameter Sets: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Inputs

System.Management.Automation.PSObject

You can pipe any object to ConvertTo-Clixml .

Outputs

System.String

The XML-based representation is returned as a collection of strings.