Skip to content

Commit 3fceb89

Browse files
charlieschmidtSean Wheeler
charlieschmidt
authored and
Sean Wheeler
committed
Cmdlet help for ConvertFrom-Clixml and ConvertTo-Clixml (#2022)
* Cmdlet help for ConvertFrom-Clixml and ConvertTo-Clixml for Powershell#3898 * minor edits - Removed -information* common parameters - reformat code blocks - renumbered example * minor updates - reformatted examples - removed common paramters * update link to about topic * minor edits - removed common parameters - formatted code blocks * minor edits - reformatted code blocks - removed common parameters
1 parent 607b9f4 commit 3fceb89

File tree

4 files changed

+360
-82
lines changed

4 files changed

+360
-82
lines changed

‎reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
ms.date: 2017-06-09
3+
schema: 2.0.0
4+
locale: en-us
5+
keywords: powershell,cmdlet
6+
online version:
7+
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
8+
title: ConvertFrom-Clixml
9+
---
10+
11+
# ConvertFrom-Clixml
12+
13+
## SYNOPSIS
14+
Converts an CLIXML string into new corresponding object in Windows PowerShell.
15+
16+
## SYNTAX
17+
18+
```
19+
ConvertFrom-Clixml -InputObject <string> [-IncludeTotalCount] [-Skip <UInt64>] [-First <UInt64>] [<CommonParameters>]
20+
```
21+
22+
## DESCRIPTION
23+
The **ConvertFrom-CliXml** cmdlet converts a CLIXML string with data that represents Microsoft .NET Framework objects and creates the objects in Windows PowerShell.
24+
25+
A valuable use of **ConvertFrom-CliXml** is to deserialize credentials and secure strings that have been serialized as secure XML by running the ConvertTo-Clixml cmdlet.
26+
For an example of how to do this, see Example 2.
27+
28+
## EXAMPLES
29+
30+
### Example 1: Import a serialized file and recreate an object
31+
32+
```powershell
33+
$clixml = Get-Process | ConvertTo-Clixml
34+
$Processes = ConvertFrom-Clixml $clixml
35+
```
36+
37+
This command uses the ConvertTo-Clixml cmdlet to create a serialized copy of the process information returned by Get-Process.
38+
It then uses **ConvertFrom-Clixml** to retrieve the contents of the serialized string and re-create an object that is stored in the $Processes variable.
39+
40+
### Example 2: Convert an encrypted credential object
41+
42+
```powershell
43+
$CredXml = $Credential | ConvertTo-Clixml
44+
$Credential = ConvertFrom-CliXml $CredXml
45+
```
46+
47+
The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the
48+
[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx).
49+
This ensures that only your user account can decrypt the contents of the credential object.
50+
51+
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.
52+
53+
To deserialize the credential later, run the second command.
54+
This time, you are running ConvertFrom-Clixml to import the secured credential object into your script.
55+
This eliminates the risk of exposing plain-text passwords in your script.
56+
57+
## PARAMETERS
58+
59+
### -InputObject
60+
Specifies the CLIXML string to be converted to objects.
61+
You can also pipe the CLIXML string to **ConvertFrom-Clixml**.
62+
63+
```yaml
64+
Type: string
65+
Parameter Sets: (All)
66+
Aliases:
67+
68+
Required: True
69+
Position: 0
70+
Default value: None
71+
Accept pipeline input: True (ByPropertyName, ByValue)
72+
Accept wildcard characters: False
73+
```
74+
75+
### -First
76+
Gets only the specified number of objects.
77+
Enter the number of objects to get.
78+
79+
```yaml
80+
Type: UInt64
81+
Parameter Sets: (All)
82+
Aliases:
83+
84+
Required: False
85+
Position: Named
86+
Default value: False
87+
Accept pipeline input: False
88+
Accept wildcard characters: False
89+
```
90+
91+
### -Skip
92+
Ignores the specified number of objects and then gets the remaining objects.
93+
Enter the number of objects to skip.
94+
95+
```yaml
96+
Type: UInt64
97+
Parameter Sets: (All)
98+
Aliases:
99+
100+
Required: False
101+
Position: Named
102+
Default value: False
103+
Accept pipeline input: False
104+
Accept wildcard characters: False
105+
```
106+
107+
### -IncludeTotalCount
108+
Reports the total number of objects in the data set (an integer) followed by the selected objects.
109+
If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value.
110+
The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not 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.
111+
112+
```yaml
113+
Type: SwitchParameter
114+
Parameter Sets: (All)
115+
Aliases:
116+
117+
Required: False
118+
Position: Named
119+
Default value: False
120+
Accept pipeline input: False
121+
Accept wildcard characters: False
122+
```
123+
124+
### CommonParameters
125+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md).
126+
127+
## INPUTS
128+
129+
### System.String
130+
You can pipe a string that contains a path to **ConvertFrom-Clixml**.
131+
132+
## OUTPUTS
133+
134+
### PSObject
135+
**ConvertFrom-Clixml** returns objects that have been deserialized from the stored XML files.
136+
137+
## NOTES
138+
* When specifying multiple values for a parameter, use commas to separate the values. For example, "\<parameter-name\> \<value1\>, \<value2\>".
139+
140+
*
141+
142+
## RELATED LINKS
143+
144+
[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx)
145+
146+
[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk)
147+
148+
[Export-Clixml](Export-Clixml.md)
149+
150+
[Import-Clixml](Import-Clixml.md)
151+
152+
[ConvertTo-Clixml](ConvertTo-Clixml.md)
153+
154+

‎reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
ms.date: 2017-06-09
3+
schema: 2.0.0
4+
locale: en-us
5+
keywords: powershell,cmdlet
6+
online version:
7+
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
8+
title: ConvertTo-Clixml
9+
---
10+
11+
# ConvertTo-Clixml
12+
13+
## SYNOPSIS
14+
Converts objects to an XML-based representation and returns that as a string.
15+
16+
## SYNTAX
17+
18+
```
19+
ConvertTo-Clixml [-Depth <Int32>] -InputObject <PSObject> [-Encoding <String>] [<CommonParameters>]
20+
```
21+
22+
## DESCRIPTION
23+
The **ConvertTo-CliXml** cmdlet creates XML-based representations of objects and returns them as strings.
24+
You can then use the **ConvertFrom-Clixml** cmdlet to re-create the saved objects based on the contents of the strings.
25+
26+
A valuable use of **ConvertTo-CliXml** is to serialize credentials and secure strings securely as XML.
27+
For an example of how to do this, see Example 3.
28+
29+
## EXAMPLES
30+
31+
### Example 1: Convert a string to an XML representation
32+
33+
```powershell
34+
"This is a test" | ConvertTo-Clixml
35+
```
36+
37+
This command returns a string with am XML-based representation of the string object with a value of "This is a test".
38+
39+
### Example 2: Convert an object to an XML-based representation
40+
41+
```powershell
42+
$FileaclString = Get-Acl C:\test.txt | ConvertTo-Clixml
43+
Fileacl = ConvertFrom-Clixml $FileaclString
44+
```
45+
46+
This example shows how to convert an object to an XML string and then create an object by converting the XML from the string.
47+
48+
The first command uses the Get-Acl cmdlet to get the security descriptor of the Test.txt file.
49+
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.
50+
Then, it saves the string in the $FileAclString variable.
51+
52+
The second command uses the ConvertFrom-Clixml cmdlet to create an object from the XML in the $FileAclString variable.
53+
Then, it saves the object in the $FileAcl variable.
54+
55+
### Example 3: Convert an encrypted credential object
56+
57+
```powershell
58+
$CredXml = $Credential | ConvertTo-Clixml
59+
$Credential = ConvertFrom-CliXml $CredXml
60+
```
61+
62+
The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the
63+
[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx).
64+
This ensures that only your user account can decrypt the contents of the credential object.
65+
66+
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.
67+
68+
To deserialize the credential later, run the second command.
69+
This time, you are running ConvertFrom-Clixml to import the secured credential object into your script.
70+
This eliminates the risk of exposing plain-text passwords in your script.
71+
72+
## PARAMETERS
73+
74+
### -Depth
75+
Specifies how many levels of contained objects are included in the XML representation.
76+
The default value is 2.
77+
78+
The default value can be overridden for the object type in the Types.ps1xml files.
79+
For more information, see about_Types.ps1xml.
80+
81+
```yaml
82+
Type: Int32
83+
Parameter Sets: (All)
84+
Aliases:
85+
86+
Required: False
87+
Position: Named
88+
Default value: None
89+
Accept pipeline input: False
90+
Accept wildcard characters: False
91+
```
92+
93+
### -Encoding
94+
Specifies the type of encoding for the target file.
95+
The acceptable values for this parameter are:
96+
97+
- ASCII
98+
- UTF8
99+
- UTF7
100+
- UTF32
101+
- Unicode
102+
- BigEndianUnicode
103+
- Default
104+
- OEM
105+
106+
The default value is Unicode.
107+
108+
```yaml
109+
Type: String
110+
Parameter Sets: (All)
111+
Aliases:
112+
Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM
113+
114+
Required: False
115+
Position: Named
116+
Default value: None
117+
Accept pipeline input: False
118+
Accept wildcard characters: False
119+
```
120+
121+
### -InputObject
122+
Specifies the object to be converted.
123+
Enter a variable that contains the objects, or type a command or expression that gets the objects.
124+
You can also pipe objects to **ConvertTo-Clixml**.
125+
126+
```yaml
127+
Type: PSObject
128+
Parameter Sets: (All)
129+
Aliases:
130+
131+
Required: True
132+
Position: Named
133+
Default value: None
134+
Accept pipeline input: True (ByValue)
135+
Accept wildcard characters: False
136+
```
137+
138+
### CommonParameters
139+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md).
140+
141+
## INPUTS
142+
143+
### System.Management.Automation.PSObject
144+
You can pipe any object to **ConvertTo-Clixml**.
145+
146+
## OUTPUTS
147+
148+
### System.String
149+
The XML-based representation is returned as a collection of strings.
150+
151+
## NOTES
152+
153+
## RELATED LINKS
154+
155+
[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx)
156+
157+
[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk)
158+
159+
[ConvertTo-Json](ConvertTo-Json.md)
160+
161+
[ConvertTo-Xml](ConvertTo-Xml.md)
162+
163+
[ConvertTo-Csv](ConvertTo-Csv.md)
164+
165+
[Export-Clixml](Export-Clixml.md)
166+
167+
[Import-Clixml](Import-Clixml.md)
168+
169+
[ConvertFrom-Clixml](ConvertFrom-Clixml.md)

0 commit comments

Comments
 (0)