ערוך

שתף באמצעות

Import-Clixml

  • Reference
Module:
Microsoft.PowerShell.Utility

Imports a CLIXML file and creates corresponding objects in PowerShell.

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.

Important

Export-Clixml only exports encrypted credentials on Windows. On non-Windows operating systems such as macOS and Linux, credentials are exported in plain text.

$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

Gets only the specified number of objects. Enter the number of objects to get.

Type:UInt64
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludeTotalCount

Reports the total number of objects in the data set followed by the selected objects. If the cmdlet can't determine the total count, it displays Unknown total count. The integer has an Accuracy property that indicates the reliability of the total count value. The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet couldn't count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LiteralPath

Specifies the path to the XML files. Unlike Path, the value of the LiteralPath parameter is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences.

Type:String[]
Aliases:PSPath
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Path

Specifies the path to the XML files.

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Skip

Ignores the specified number of objects and then gets the remaining objects. Enter the number of objects to skip.

Type:UInt64
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

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