Import-Clixml

Syntax

Import-Clixml
      [-Path] <String[]>
      [-IncludeTotalCount]
      [-Skip <UInt64>]
      [-First <UInt64>]
      [<CommonParameters>]

Import-Clixml
      -LiteralPath <String[]>
      [-IncludeTotalCount]
      [-Skip <UInt64>]
      [-First <UInt64>]
      [<CommonParameters>]

Description

The Import-Clixml cmdlet imports objects that have been serialized into a Common Language Infrastructure (CLI) XML file. A valuable use of Import-Clixml on Windows computers is to import credentials and secure strings that were exported as secure XML using Export-Clixml. Example #2 shows how to use Import-Clixml to import a secure credential object.

The CLIXML data is deserialized back into PowerShell objects. However, the deserialized objects aren't a live objects. They are a snapshot of the objects at the time of serialization. The deserialized objects include properties but no methods.

The TypeNames property contains the original type name prefixed with Deserialized. Example #3 show the TypeNames property of a deserialized object.

Import-Clixml uses the byte-order-mark (BOM) to detect the encoding format of the file. If the file has no BOM, it assumes the encoding is UTF8.

For more information about CLI, see Language independence.

Examples

Example 1: Import a serialized file and recreate an object

This example uses the Export-Clixml cmdlet to save a serialized copy of the process information returned by Get-Process. Import-Clixml retrieves the serialized file's contents and recreates an object that is stored in the $Processes variable.

Get-Process | Export-Clixml -Path .\pi.xml
$Processes = Import-Clixml -Path .\pi.xml

Example 2: Import a secure 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 Export-Clixml cmdlet to save the credential to disk.

$Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential
$Credential | Export-Clixml $Credxmlpath
$Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential
$Credential = Import-Clixml $Credxmlpath

The Export-Clixml cmdlet encrypts credential objects by using the Windows Data Protection API. The encryption ensures that only your user account can decrypt the contents of the credential object. The exported CLIXML file can't be used on a different computer or by a different user.

In the example, the file in which the credential is stored is represented by TestScript.ps1.credential. Replace TestScript with the name of the script with which you're loading the credential.

You send the credential object down the pipeline to Export-Clixml, and save it to the path, $Credxmlpath, that you specified in the first command.

To import the credential automatically into your script, run the final two commands. Run Import-Clixml to import the secured credential object into your script. This import eliminates the risk of exposing plain-text passwords in your script.

Example 3: Inspect the TypeNames property of a deserialized object

This example shows importing an object stored as CLIXML data. The data is deserialized back into a PowerShell object. However, the deserialized object aren't a live objects. They are a snapshot of the objects at the time of serialization. The deserialized objects include properties but no methods.

$original = [pscustomobject] @{
    Timestamp = Get-Date
    Label     = 'Meeting event'
}
$original | Add-Member -MemberType ScriptMethod -Name GetDisplay -Value {
    '{0:yyyy-MM-dd HH:mm} {1}' -f $this.Timestamp, $this.Label
}
$original | Get-Member -MemberType ScriptMethod

TypeName: System.Management.Automation.PSCustomObject

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
Label       NoteProperty string Label=Meeting event
Timestamp   NoteProperty System.DateTime Timestamp=1/31/2024 2:27:59 PM
GetDisplay  ScriptMethod System.Object GetDisplay();

$original | Export-Clixml -Path event.clixml
$deserialized = Import-CliXml -Path event.clixml
$deserialized | Get-Member

TypeName: Deserialized.System.Management.Automation.PSCustomObject

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
Label       NoteProperty string Label=Meeting event
Timestamp   NoteProperty System.DateTime Timestamp=1/31/2024 2:27:59 PM

Note that the type of the object in $original is System.Management.Automation.PSCustomObject, but the type of the object in $deserialized is Deserialized.System.Management.Automation.PSCustomObject. Also, the GetDisplay() method is missing from the deserialized object.

Parameters

-First

-IncludeTotalCount

-LiteralPath

-Path

-Skip

Inputs

String

You can pipe a string containing a path to this cmdlet.

Outputs

PSObject

This cmdlet returns objects that were deserialized from the stored XML files.

Notes

When specifying multiple values for a parameter, use commas to separate the values. For example, <parameter-name> <value1>, <value2>.

Related Links

• Export-Clixml
• Introducing XML Serialization
• Join-Path
• Securely Store Credentials on Disk
• Use PowerShell to Pass Credentials to Legacy Systems