Fixes #10843 - Explain deserialized object and add example (#10844)

* Explain deserialized object and add example

* Copy changes and fix bookmark

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Output.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how to interpret and format the output of remote commands.
 Locale: en-US
-ms.date: 07/03/2023
+ms.date: 01/31/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote_output?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Remote Output
@@ -95,10 +95,9 @@ Monday, July 21, 2008 7:16:58 PM    Server02
 When you run remote commands that generate output, the command output is
 transmitted across the network back to the local computer.
 
-Because most live Microsoft .NET objects, like the objects that PowerShell
-cmdlets return, can't be transmitted over the network. The live objects are
-_serialized_ or converted into XML representations of the object and its
-properties. Then, PowerShell transmits the serialized object across the
+Since live .NET objects can't be transmitted over the network, the live objects
+are _serialized_ or converted into XML representations of the object and its
+properties. PowerShell transmits the serialized object across the
 network.
 
 On the local computer, PowerShell receives the serialized object and
@@ -139,7 +138,7 @@ determines the order in which PowerShell connects to the remote computers.
 However, the results appear in the order that the data is received from the
 remote computers.
 
-You can use the `Sort-Object` cmdlet to sort the results on the
+You can use the `Sort-Object` cmdlet to sort the results on on the
 **PSComputerName**. When you any other property of the object, the results from
 different computers are interspersed interleaved in the output
 

reference/5.1/Microsoft.PowerShell.Utility/Export-Clixml.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 01/31/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/export-clixml?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Export-Clixml
@@ -31,10 +31,10 @@ Export-Clixml -LiteralPath <String> -InputObject <PSObject> [-Depth <Int32>] [-F
 
 ## DESCRIPTION
 
-The `Export-Clixml` cmdlet creates a Common Language Infrastructure (CLI) XML-based representation
-of an object or objects and stores it in a file. You can then use the `Import-Clixml` cmdlet to
-recreate the saved object based on the contents of that file.
-For more information about CLI, see [Language independence](/dotnet/standard/language-independence).
+The `Export-Clixml` cmdlet serialized an object into a Common Language Infrastructure (CLI)
+XML-based representation stores it in a file. You can then use the `Import-Clixml` cmdlet to
+recreate the saved object based on the contents of that file. For more information about CLI, see
+[Language independence](/dotnet/standard/language-independence).
 
 This cmdlet is similar to `ConvertTo-Xml`, except that `Export-Clixml` stores the resulting XML in a
 file. `ConvertTo-XML` returns the XML, so you can continue to process it in PowerShell.
@@ -53,7 +53,7 @@ string **This is a test**.
 "This is a test" | Export-Clixml -Path .\sample.xml
 ```
 
-The string **This is a test** is sent down the pipeline. `Export-Clixml` uses the **Path** parameter
+The string `This is a test` is sent down the pipeline. `Export-Clixml` uses the **Path** parameter
 to create an XML file named `sample.xml` in the current directory.
 
 ### Example 2: Export an object to an XML file
@@ -80,7 +80,8 @@ In this example, given a credential that you've stored in the `$Credential` vari
 
 > [!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.
+> such as macOS and Linux, credentials are exported as a plain text stored as a Unicode character
+> array. This provides some obfuscation but does not provide encryption.
 
 ```powershell
 $Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential
@@ -89,10 +90,10 @@ $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](/previous-versions/windows/apps/hh464970(v=win.10)).
-The encryption ensures that only your user account on only that computer 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.
+The `Export-Clixml` cmdlet encrypts credential objects by using the Windows
+[Data Protection API](/previous-versions/windows/apps/hh464970(v=win.10)). The encryption ensures
+that only your user account on only that computer 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
@@ -279,7 +280,8 @@ Accept wildcard characters: False
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+-WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 

reference/5.1/Microsoft.PowerShell.Utility/Import-Clixml.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 01/31/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/import-clixml?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Import-Clixml
@@ -31,16 +31,26 @@ Import-Clixml -LiteralPath <String[]> [-IncludeTotalCount] [-Skip <UInt64>] [-Fi
 
 ## DESCRIPTION
 
-The `Import-Clixml` cmdlet imports a Common Language Infrastructure (CLI) XML file with data that
-represents Microsoft .NET Framework objects and creates the PowerShell objects. For more information
-about CLI, see [Language independence](/dotnet/standard/language-independence).
+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](#example-2-import-a-secure-credential-object) shows how to use `Import-Clixml` to
+import a secure credential object.
 
-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`. For an example, see Example 2.
+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](#example-3-inspect-the-typenames-property-of-a-deserialized-object) 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](/dotnet/standard/language-independence).
+
 ## EXAMPLES
 
 ### Example 1: Import a serialized file and recreate an object
@@ -70,9 +80,10 @@ $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](/previous-versions/windows/apps/hh464970(v=win.10)).
-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.
+The `Export-Clixml` cmdlet encrypts credential objects by using the Windows
+[Data Protection API](/previous-versions/windows/apps/hh464970(v=win.10)). 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
@@ -85,6 +96,62 @@ To import the credential automatically into your script, run the final two comma
 `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.
+
+```powershell
+$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
+```
+
+```Output
+   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();
+```
+
+```powershell
+$original | Export-Clixml -Path event.clixml
+$deserialized = Import-CliXml -Path event.clixml
+$deserialized | Get-Member
+```
+
+```Output
+   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
@@ -180,7 +247,8 @@ Accept wildcard characters: False
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+-WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 

reference/7.2/Microsoft.PowerShell.Core/About/about_Remote_Output.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how to interpret and format the output of remote commands.
 Locale: en-US
-ms.date: 07/03/2023
+ms.date: 01/31/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote_output?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Remote Output
@@ -95,10 +95,9 @@ Monday, July 21, 2008 7:16:58 PM    Server02
 When you run remote commands that generate output, the command output is
 transmitted across the network back to the local computer.
 
-Because most live Microsoft .NET objects, like the objects that PowerShell
-cmdlets return, can't be transmitted over the network. The live objects are
-_serialized_ or converted into XML representations of the object and its
-properties. Then, PowerShell transmits the serialized object across the
+Since live .NET objects can't be transmitted over the network, the live objects
+are _serialized_ or converted into XML representations of the object and its
+properties. PowerShell transmits the serialized object across the
 network.
 
 On the local computer, PowerShell receives the serialized object and

reference/7.2/Microsoft.PowerShell.Utility/Export-Clixml.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 01/31/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/export-clixml?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Export-Clixml
@@ -333,7 +333,8 @@ Accept wildcard characters: False
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+-WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 

reference/7.2/Microsoft.PowerShell.Utility/Import-Clixml.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 01/31/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/import-clixml?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Import-Clixml
@@ -31,16 +31,26 @@ Import-Clixml -LiteralPath <String[]> [-IncludeTotalCount] [-Skip <UInt64>] [-Fi
 
 ## DESCRIPTION
 
-The `Import-Clixml` cmdlet imports a Common Language Infrastructure (CLI) XML file with data that
-represents Microsoft .NET Framework objects and creates the PowerShell objects. For more information
-about CLI, see [Language independence](/dotnet/standard/language-independence).
+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](#example-2-import-a-secure-credential-object) shows how to use `Import-Clixml` to
+import a secure credential object.
 
-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`. For an example, see Example 2.
+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](#example-3-inspect-the-typenames-property-of-a-deserialized-object) 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](/dotnet/standard/language-independence).
+
 ## EXAMPLES
 
 ### Example 1: Import a serialized file and recreate an object
@@ -70,9 +80,10 @@ $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](/previous-versions/windows/apps/hh464970(v=win.10)).
-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.
+The `Export-Clixml` cmdlet encrypts credential objects by using the Windows
+[Data Protection API](/previous-versions/windows/apps/hh464970(v=win.10)). 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
@@ -85,6 +96,62 @@ To import the credential automatically into your script, run the final two comma
 `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.
+
+```powershell
+$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
+```
+
+```Output
+   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();
+```
+
+```powershell
+$original | Export-Clixml -Path event.clixml
+$deserialized = Import-CliXml -Path event.clixml
+$deserialized | Get-Member
+```
+
+```Output
+   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
@@ -180,7 +247,8 @@ Accept wildcard characters: False
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+-WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS