From 2244c2fc583ead13299586c233cb9b4bf831424d Mon Sep 17 00:00:00 2001 From: Jos Koelewijn Date: Sat, 29 Feb 2020 12:10:58 +0100 Subject: [PATCH 1/5] add more information about 'using' scope modifier --- .../About/about_Remote_Variables.md | 47 +++++++++++++++++-- .../About/about_Remote_Variables.md | 44 +++++++++++++++-- .../About/about_Remote_Variables.md | 45 ++++++++++++++++-- .../About/about_Remote_Variables.md | 45 ++++++++++++++++-- 4 files changed, 169 insertions(+), 12 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index a3e3df20800a..7104f35fe488 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -105,14 +105,53 @@ $Splat = @{ Name = "Win*"; Include = "WinRM" } Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ``` -## Using local variables in PowerShell 2.0 +### Other situations where the 'Using' scope modifier is needed + +For anything that executes out-of-runspace, doesn't execute directly in the +caller's runspace, you need the `Using` scope modifier in order to embed +variable values from the caller's scope, so that the out-of-runspace code +can access it. (Conversely, all other contexts neither require nor support the +'Using' scope modifier.) Specifically, this includes the following contexts: + +- Remotely executed commands, started with Invoke-Command's `-ComputerName` or + `-Session` parameter (remote runspace) +- Background jobs, started with Start-Job (out-of-process runspace) +- Thread jobs, started via Start-ThreadJob (separate runspace) +- InlineScript in Workflows (out-of-process) + +> [!NOTE] +> Note that out-of-runspace code can never modify variables in the caller's +> scope. However, in the case of thread jobs (but not during remoting and not in +> background jobs), if the variable value happens to be an instance of a reference +> type (like a collection type), it is possible to modify that instance in +> another thread, which requires synchronizing the modifications across threads, +> should multiple threads perform modifications. + +## Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. For values +in variables to cross these process boundaries they undergo XML-based +serialization and deserialization. This typically involves loss of type fidelity +\- both on input and output. --> todo: example needed + +Thread jobs, by contrast, because they run in a different runspace (thread) in +the same process receive $using: variable values as their original, live objects +and, similarly, return such objects. + +The caveat is that explicit synchronization across runspaces (threads) may be +needed, if they all access a given, mutable object - which is most likely to +happen with ForEach-Object -Parallel. + +Generally, though, thread jobs are the better alternative to background jobs in +most cases, due to their significantly better performance, lower resource use, +and type fidelity. + +## Using local variables with `-ArgumentList` parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` cmdlet to specify the local variable as the parameter value. -The following command format is valid on PowerShell 2.0 and later versions: - - Use the `param` keyword to define parameters for the remote command. The parameter names are placeholders that don't need to match the local variable's name. @@ -144,6 +183,8 @@ Invoke-Command -ComputerName S1 -ScriptBlock { [about_Splatting](about_Splatting.md) +[about_Variables](about_Variables.md) + [Enter-PSSession](../Enter-PSSession.md) [Invoke-Command](../Invoke-Command.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 8a9df50c0241..b1e077aa78dc 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -105,14 +105,52 @@ $Splat = @{ Name = "Win*"; Include = "WinRM" } Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ``` -## Using local variables in PowerShell 2.0 +### Other situations where the 'Using' scope modifier is needed + +For anything that executes out-of-runspace, doesn't execute directly in the +caller's runspace, you need the `Using` scope modifier in order to embed +variable values from the caller's scope, so that the out-of-runspace code +can access it. (Conversely, all other contexts neither require nor support the +'Using' scope modifier.) Specifically, this includes the following contexts: + +- Remotely executed commands, started with Invoke-Command's `-ComputerName` or + `-Session` parameter (remote runspace) +- Background jobs, started with Start-Job (out-of-process runspace) +- Thread jobs, started via Start-ThreadJob (separate runspace) + +> [!NOTE] +> Note that out-of-runspace code can never modify variables in the caller's +> scope. However, in the case of thread jobs (but not during remoting and not in +> background jobs), if the variable value happens to be an instance of a reference +> type (like a collection type), it is possible to modify that instance in +> another thread, which requires synchronizing the modifications across threads, +> should multiple threads perform modifications. + +## Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. For values +in variables to cross these process boundaries they undergo XML-based +serialization and deserialization. This typically involves loss of type fidelity +\- both on input and output. --> todo: example needed + +Thread jobs, by contrast, because they run in a different runspace (thread) in +the same process receive $using: variable values as their original, live objects +and, similarly, return such objects. + +The caveat is that explicit synchronization across runspaces (threads) may be +needed, if they all access a given, mutable object - which is most likely to +happen with ForEach-Object -Parallel. + +Generally, though, thread jobs are the better alternative to background jobs in +most cases, due to their significantly better performance, lower resource use, +and type fidelity. + +## Using local variables with `-ArgumentList` parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` cmdlet to specify the local variable as the parameter value. -The following command format is valid on PowerShell 2.0 and later versions: - - Use the `param` keyword to define parameters for the remote command. The parameter names are placeholders that don't need to match the local variable's name. diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index bdcf4eb5a41d..a4ec898a1953 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -105,14 +105,53 @@ $Splat = @{ Name = "Win*"; Include = "WinRM" } Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ``` -## Using local variables in PowerShell 2.0 +### Other situations where the 'Using' scope modifier is needed + +For anything that executes out-of-runspace, doesn't execute directly in the +caller's runspace, you need the `Using` scope modifier in order to embed +variable values from the caller's scope, so that the out-of-runspace code +can access it. (Conversely, all other contexts neither require nor support the +'Using' scope modifier.) Specifically, this includes the following contexts: + +- Remotely executed commands, started with Invoke-Command's `-ComputerName` or + `-Session` parameter (remote runspace) +- Background jobs, started with Start-Job (out-of-process runspace) +- Thread jobs, started via Start-ThreadJob or ForEach-Object -Parallel + (separate runspace) + +> [!NOTE] +> Note that out-of-runspace code can never modify variables in the caller's +> scope. However, in the case of thread jobs (but not during remoting and not in +> background jobs), if the variable value happens to be an instance of a reference +> type (like a collection type), it is possible to modify that instance in +> another thread, which requires synchronizing the modifications across threads, +> should multiple threads perform modifications. + +## Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. For values +in variables to cross these process boundaries they undergo XML-based +serialization and deserialization. This typically involves loss of type fidelity +\- both on input and output. --> todo: example needed + +Thread jobs, by contrast, because they run in a different runspace (thread) in +the same process receive $using: variable values as their original, live objects +and, similarly, return such objects. + +The caveat is that explicit synchronization across runspaces (threads) may be +needed, if they all access a given, mutable object - which is most likely to +happen with ForEach-Object -Parallel. + +Generally, though, thread jobs are the better alternative to background jobs in +most cases, due to their significantly better performance, lower resource use, +and type fidelity. + +## Using local variables with `-ArgumentList` parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` cmdlet to specify the local variable as the parameter value. -The following command format is valid on PowerShell 2.0 and later versions: - - Use the `param` keyword to define parameters for the remote command. The parameter names are placeholders that don't need to match the local variable's name. diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 72dee3240a7d..9fbb06ae4f65 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -105,14 +105,53 @@ $Splat = @{ Name = "Win*"; Include = "WinRM" } Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ``` -## Using local variables in PowerShell 2.0 +### Other situations where the 'Using' scope modifier is needed + +For anything that executes out-of-runspace, doesn't execute directly in the +caller's runspace, you need the `Using` scope modifier in order to embed +variable values from the caller's scope, so that the out-of-runspace code +can access it. (Conversely, all other contexts neither require nor support the +'Using' scope modifier.) Specifically, this includes the following contexts: + +- Remotely executed commands, started with Invoke-Command's `-ComputerName` or + `-Session` parameter (remote runspace) +- Background jobs, started with Start-Job (out-of-process runspace) +- Thread jobs, started via Start-ThreadJob or ForEach-Object -Parallel + (separate runspace) + +> [!NOTE] +> Note that out-of-runspace code can never modify variables in the caller's +> scope. However, in the case of thread jobs (but not during remoting and not in +> background jobs), if the variable value happens to be an instance of a reference +> type (like a collection type), it is possible to modify that instance in +> another thread, which requires synchronizing the modifications across threads, +> should multiple threads perform modifications. + +## Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. For values +in variables to cross these process boundaries they undergo XML-based +serialization and deserialization. This typically involves loss of type fidelity +\- both on input and output. --> todo: example needed + +Thread jobs, by contrast, because they run in a different runspace (thread) in +the same process receive $using: variable values as their original, live objects +and, similarly, return such objects. + +The caveat is that explicit synchronization across runspaces (threads) may be +needed, if they all access a given, mutable object - which is most likely to +happen with ForEach-Object -Parallel. + +Generally, though, thread jobs are the better alternative to background jobs in +most cases, due to their significantly better performance, lower resource use, +and type fidelity. + +## Using local variables with `-ArgumentList` parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` cmdlet to specify the local variable as the parameter value. -The following command format is valid on PowerShell 2.0 and later versions: - - Use the `param` keyword to define parameters for the remote command. The parameter names are placeholders that don't need to match the local variable's name. From 00e19e5e0933f2fb3d8a1c5e193566a2d35a58d4 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 13 Mar 2020 18:55:08 -0700 Subject: [PATCH 2/5] editorial feedback --- .../About/about_Remote_Variables.md | 57 +++++--------- .../About/about_Scopes.md | 35 ++++++++- .../About/about_Remote_Variables.md | 77 ++++++++----------- .../About/about_Scopes.md | 35 ++++++++- .../About/about_Remote_Variables.md | 63 +++++++-------- .../About/about_Scopes.md | 37 ++++++++- .../About/about_Remote_Variables.md | 63 +++++++-------- .../About/about_Scopes.md | 37 ++++++++- 8 files changed, 244 insertions(+), 160 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 7104f35fe488..0395e0575dc8 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 07/23/2019 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote_variables?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Remote_Variables @@ -107,46 +107,30 @@ Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ### Other situations where the 'Using' scope modifier is needed -For anything that executes out-of-runspace, doesn't execute directly in the -caller's runspace, you need the `Using` scope modifier in order to embed -variable values from the caller's scope, so that the out-of-runspace code -can access it. (Conversely, all other contexts neither require nor support the -'Using' scope modifier.) Specifically, this includes the following contexts: - -- Remotely executed commands, started with Invoke-Command's `-ComputerName` or - `-Session` parameter (remote runspace) -- Background jobs, started with Start-Job (out-of-process runspace) -- Thread jobs, started via Start-ThreadJob (separate runspace) -- InlineScript in Workflows (out-of-process) - -> [!NOTE] -> Note that out-of-runspace code can never modify variables in the caller's -> scope. However, in the case of thread jobs (but not during remoting and not in -> background jobs), if the variable value happens to be an instance of a reference -> type (like a collection type), it is possible to modify that instance in -> another thread, which requires synchronizing the modifications across threads, -> should multiple threads perform modifications. +For any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: -## Serialization of variable values - -Remotely executed commands and background jobs run out-of-process. For values -in variables to cross these process boundaries they undergo XML-based -serialization and deserialization. This typically involves loss of type fidelity -\- both on input and output. --> todo: example needed +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` (separate thread session) -Thread jobs, by contrast, because they run in a different runspace (thread) in -the same process receive $using: variable values as their original, live objects -and, similarly, return such objects. +Depending on the context, embedded variables are copied values of the variables +in the caller's scope. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. -The caveat is that explicit synchronization across runspaces (threads) may be -needed, if they all access a given, mutable object - which is most likely to -happen with ForEach-Object -Parallel. +## Serialization of variable values -Generally, though, thread jobs are the better alternative to background jobs in -most cases, due to their significantly better performance, lower resource use, -and type fidelity. +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. -## Using local variables with `-ArgumentList` parameter +## Using local variables with **ArgumentList** parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` @@ -190,3 +174,4 @@ Invoke-Command -ComputerName S1 -ScriptBlock { [Invoke-Command](../Invoke-Command.md) [New-PSSession](../New-PSSession.md) + diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md index bc31b4983219..2546625c72f3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 01/23/2020 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_scopes @@ -191,10 +191,41 @@ Using is a special scope modifier that identifies a local variable in a remote command. Without a modifier, PowerShell expects variables in remote commands to be defined in the remote session. -The Using scope modifier is introduced in PowerShell 3.0. +The `Using` scope modifier is introduced in PowerShell 3.0. + +r any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: + +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` (separate runspace) + +Depending on the context, embedded variables are copies values or references to +the caller's scope variables. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. For more information, see [about_Remote_Variables](about_Remote_Variables.md). +But for thread jobs receive references to variables. This means it is possible +to modify call scope variables in a different thread. To safely modify +variables requires thread synchronization. + +For more information see: + +- [Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) + +#### Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. + ### The AllScope Option Variables and aliases have an **Option** property that can take a value of diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index b1e077aa78dc..03becf4e8a7f 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 07/23/2019 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote_variables?view=powershell-6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Remote_Variables @@ -44,14 +44,6 @@ Invoke-Command -Session $s -ScriptBlock {$ps = "*PowerShell*"} Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $ps} ``` -The `Using` scope modifier cannot be used to modify a local variable from **PSSession**. - -```powershell -$s = New-PSSession -ComputerName S1 -$ps = "*PowerShell*" -Invoke-Command -Session $s -ScriptBlock {$Using:ps = 'Cannot assign new value'} -``` - ## Using local variables You can use local variables in remote commands, but the variable must be @@ -77,6 +69,14 @@ Invoke-Command -ComputerName S1 -ScriptBlock { } ``` +The `Using` scope modifier can be used in a **PSSession**. + +```powershell +$s = New-PSSession -ComputerName S1 +$ps = "*PowerShell*" +Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +``` + A variable reference such as `$using:var` expands to the value of variable `$var` from the caller's context. You do not get access to the caller's variable object. The `Using` scope modifier cannot be used to modify a local variable within the @@ -85,7 +85,7 @@ The `Using` scope modifier cannot be used to modify a local variable within the ```powershell $s = New-PSSession -ComputerName S1 $ps = "*PowerShell*" -Invoke-Command -Session $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +Invoke-Command -Session $s -ScriptBlock {$Using:ps = 'Cannot assign new value'} ``` For more information about `Using`, see [about_Scopes](./about_Scopes.md) @@ -107,45 +107,30 @@ Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ### Other situations where the 'Using' scope modifier is needed -For anything that executes out-of-runspace, doesn't execute directly in the -caller's runspace, you need the `Using` scope modifier in order to embed -variable values from the caller's scope, so that the out-of-runspace code -can access it. (Conversely, all other contexts neither require nor support the -'Using' scope modifier.) Specifically, this includes the following contexts: - -- Remotely executed commands, started with Invoke-Command's `-ComputerName` or - `-Session` parameter (remote runspace) -- Background jobs, started with Start-Job (out-of-process runspace) -- Thread jobs, started via Start-ThreadJob (separate runspace) - -> [!NOTE] -> Note that out-of-runspace code can never modify variables in the caller's -> scope. However, in the case of thread jobs (but not during remoting and not in -> background jobs), if the variable value happens to be an instance of a reference -> type (like a collection type), it is possible to modify that instance in -> another thread, which requires synchronizing the modifications across threads, -> should multiple threads perform modifications. +For any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: -## Serialization of variable values - -Remotely executed commands and background jobs run out-of-process. For values -in variables to cross these process boundaries they undergo XML-based -serialization and deserialization. This typically involves loss of type fidelity -\- both on input and output. --> todo: example needed +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` (separate thread session) -Thread jobs, by contrast, because they run in a different runspace (thread) in -the same process receive $using: variable values as their original, live objects -and, similarly, return such objects. +Depending on the context, embedded variables are copied values of the variables +in the caller's scope. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. -The caveat is that explicit synchronization across runspaces (threads) may be -needed, if they all access a given, mutable object - which is most likely to -happen with ForEach-Object -Parallel. +## Serialization of variable values -Generally, though, thread jobs are the better alternative to background jobs in -most cases, due to their significantly better performance, lower resource use, -and type fidelity. +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. -## Using local variables with `-ArgumentList` parameter +## Using local variables with **ArgumentList** parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` @@ -182,8 +167,12 @@ Invoke-Command -ComputerName S1 -ScriptBlock { [about_Splatting](about_Splatting.md) +[about_Variables](about_Variables.md) + [Enter-PSSession](../Enter-PSSession.md) [Invoke-Command](../Invoke-Command.md) [New-PSSession](../New-PSSession.md) + +[Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md index 56df7b1249d5..cc1ce0976057 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 01/23/2020 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_scopes @@ -191,10 +191,41 @@ Using is a special scope modifier that identifies a local variable in a remote command. Without a modifier, PowerShell expects variables in remote commands to be defined in the remote session. -The Using scope modifier is introduced in PowerShell 3.0. +The `Using` scope modifier is introduced in PowerShell 3.0. + +r any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: + +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` (separate runspace) + +Depending on the context, embedded variables are copies values or references to +the caller's scope variables. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. For more information, see [about_Remote_Variables](about_Remote_Variables.md). +But for thread jobs receive references to variables. This means it is possible +to modify call scope variables in a different thread. To safely modify +variables requires thread synchronization. + +For more information see: + +- [Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) + +#### Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. + ### The AllScope Option Variables and aliases have an **Option** property that can take a value of diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index a4ec898a1953..bf129a97b02d 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 07/23/2019 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote_variables?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Remote_Variables @@ -107,46 +107,31 @@ Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ### Other situations where the 'Using' scope modifier is needed -For anything that executes out-of-runspace, doesn't execute directly in the -caller's runspace, you need the `Using` scope modifier in order to embed -variable values from the caller's scope, so that the out-of-runspace code -can access it. (Conversely, all other contexts neither require nor support the -'Using' scope modifier.) Specifically, this includes the following contexts: - -- Remotely executed commands, started with Invoke-Command's `-ComputerName` or - `-Session` parameter (remote runspace) -- Background jobs, started with Start-Job (out-of-process runspace) -- Thread jobs, started via Start-ThreadJob or ForEach-Object -Parallel - (separate runspace) - -> [!NOTE] -> Note that out-of-runspace code can never modify variables in the caller's -> scope. However, in the case of thread jobs (but not during remoting and not in -> background jobs), if the variable value happens to be an instance of a reference -> type (like a collection type), it is possible to modify that instance in -> another thread, which requires synchronizing the modifications across threads, -> should multiple threads perform modifications. +For any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: -## Serialization of variable values - -Remotely executed commands and background jobs run out-of-process. For values -in variables to cross these process boundaries they undergo XML-based -serialization and deserialization. This typically involves loss of type fidelity -\- both on input and output. --> todo: example needed +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` + (separate thread session) -Thread jobs, by contrast, because they run in a different runspace (thread) in -the same process receive $using: variable values as their original, live objects -and, similarly, return such objects. +Depending on the context, embedded variables are copied values of the variables +in the caller's scope. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. -The caveat is that explicit synchronization across runspaces (threads) may be -needed, if they all access a given, mutable object - which is most likely to -happen with ForEach-Object -Parallel. +## Serialization of variable values -Generally, though, thread jobs are the better alternative to background jobs in -most cases, due to their significantly better performance, lower resource use, -and type fidelity. +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. -## Using local variables with `-ArgumentList` parameter +## Using local variables with **ArgumentList** parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` @@ -183,8 +168,14 @@ Invoke-Command -ComputerName S1 -ScriptBlock { [about_Splatting](about_Splatting.md) +[about_Variables](about_Variables.md) + [Enter-PSSession](../Enter-PSSession.md) [Invoke-Command](../Invoke-Command.md) [New-PSSession](../New-PSSession.md) + +[Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) + +[ForEach-Object](../ForEach-Object.md#notes) diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md index aad5d98cf8a1..94a200255c88 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 01/23/2020 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_scopes @@ -191,10 +191,43 @@ Using is a special scope modifier that identifies a local variable in a remote command. Without a modifier, PowerShell expects variables in remote commands to be defined in the remote session. -The Using scope modifier is introduced in PowerShell 3.0. +The `Using` scope modifier is introduced in PowerShell 3.0. + +r any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: + +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` + (separate runspace) + +Depending on the context, embedded variables are copies values or references to +the caller's scope variables. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. For more information, see [about_Remote_Variables](about_Remote_Variables.md). +But for thread jobs receive references to variables. This means it is possible +to modify call scope variables in a different thread. To safely modify +variables requires thread synchronization. + +For more information see: + +- [Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) +- [ForEach-Object](../ForEach-Object.md#notes) + +#### Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. + ### The AllScope Option Variables and aliases have an **Option** property that can take a value of diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 9fbb06ae4f65..d1b8b9844c64 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 07/23/2019 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote_variables?view=powershell-7.x&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Remote_Variables @@ -107,46 +107,31 @@ Invoke-Command -Session $s -ScriptBlock { Get-Service @Using:Splat } ### Other situations where the 'Using' scope modifier is needed -For anything that executes out-of-runspace, doesn't execute directly in the -caller's runspace, you need the `Using` scope modifier in order to embed -variable values from the caller's scope, so that the out-of-runspace code -can access it. (Conversely, all other contexts neither require nor support the -'Using' scope modifier.) Specifically, this includes the following contexts: - -- Remotely executed commands, started with Invoke-Command's `-ComputerName` or - `-Session` parameter (remote runspace) -- Background jobs, started with Start-Job (out-of-process runspace) -- Thread jobs, started via Start-ThreadJob or ForEach-Object -Parallel - (separate runspace) - -> [!NOTE] -> Note that out-of-runspace code can never modify variables in the caller's -> scope. However, in the case of thread jobs (but not during remoting and not in -> background jobs), if the variable value happens to be an instance of a reference -> type (like a collection type), it is possible to modify that instance in -> another thread, which requires synchronizing the modifications across threads, -> should multiple threads perform modifications. +For any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: -## Serialization of variable values - -Remotely executed commands and background jobs run out-of-process. For values -in variables to cross these process boundaries they undergo XML-based -serialization and deserialization. This typically involves loss of type fidelity -\- both on input and output. --> todo: example needed +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` + (separate thread session) -Thread jobs, by contrast, because they run in a different runspace (thread) in -the same process receive $using: variable values as their original, live objects -and, similarly, return such objects. +Depending on the context, embedded variables are copied values of the variables +in the caller's scope. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. -The caveat is that explicit synchronization across runspaces (threads) may be -needed, if they all access a given, mutable object - which is most likely to -happen with ForEach-Object -Parallel. +## Serialization of variable values -Generally, though, thread jobs are the better alternative to background jobs in -most cases, due to their significantly better performance, lower resource use, -and type fidelity. +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. -## Using local variables with `-ArgumentList` parameter +## Using local variables with **ArgumentList** parameter You can use local variables in a remote command by defining parameters for the remote command and using the **ArgumentList** parameter of the `Invoke-Command` @@ -183,8 +168,14 @@ Invoke-Command -ComputerName S1 -ScriptBlock { [about_Splatting](about_Splatting.md) +[about_Variables](about_Variables.md) + [Enter-PSSession](../Enter-PSSession.md) [Invoke-Command](../Invoke-Command.md) [New-PSSession](../New-PSSession.md) + +[Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) + +[ForEach-Object](../ForEach-Object.md#notes) diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md index 265fab93f8db..10dde5bd806f 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -1,7 +1,7 @@ --- keywords: powershell,cmdlet locale: en-us -ms.date: 01/23/2020 +ms.date: 03/13/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.x&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_scopes @@ -191,10 +191,43 @@ Using is a special scope modifier that identifies a local variable in a remote command. Without a modifier, PowerShell expects variables in remote commands to be defined in the remote session. -The Using scope modifier is introduced in PowerShell 3.0. +The `Using` scope modifier is introduced in PowerShell 3.0. + +r any script or command that executes out of session, you need the `Using` +scope modifier to embed variable values from the calling session scope, so that +out of session code can access them. The `Using` scope modifier is supported in +the following contexts: + +- Remotely executed commands, started with `Invoke-Command` using the + **ComputerName** or **Session** parameter (remote session) +- Background jobs, started with `Start-Job` (out-of-process session) +- Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` + (separate runspace) + +Depending on the context, embedded variables are copies values or references to +the caller's scope variables. Out-of-process sessions, such as remote sessions, +background jobs, and workflows, receive values of variables through the +PowerShell serialization system. For more information, see [about_Remote_Variables](about_Remote_Variables.md). +But for thread jobs receive references to variables. This means it is possible +to modify call scope variables in a different thread. To safely modify +variables requires thread synchronization. + +For more information see: + +- [Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md) +- [ForEach-Object](../ForEach-Object.md#notes) + +#### Serialization of variable values + +Remotely executed commands and background jobs run out-of-process. PowerShell +uses XML-based serialization and deserialization to make the values of +variables available across the process boundaries. The serialization process +converts objects to a **PSObject** type. The **PSObject** is general type that +contains the original objects properties but not its methods. + ### The AllScope Option Variables and aliases have an **Option** property that can take a value of From 6b7b7caa4d1a98969c012d1933209ae4d6fcb399 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 17 Mar 2020 12:10:11 -0700 Subject: [PATCH 3/5] feedback edits --- .../About/about_Remote_Variables.md | 26 ++++++++++------- .../About/about_Scopes.md | 20 +++++++------ .../About/about_Remote_Variables.md | 28 +++++++++++-------- .../About/about_Scopes.md | 22 ++++++++------- .../About/about_Remote_Variables.md | 26 ++++++++++------- .../About/about_Scopes.md | 22 ++++++++------- .../About/about_Remote_Variables.md | 26 ++++++++++------- .../About/about_Scopes.md | 22 ++++++++------- 8 files changed, 112 insertions(+), 80 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 0395e0575dc8..20af8098352b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -115,20 +115,25 @@ the following contexts: - Remotely executed commands, started with `Invoke-Command` using the **ComputerName** or **Session** parameter (remote session) - Background jobs, started with `Start-Job` (out-of-process session) -- Thread jobs, started via `Start-ThreadJob` (separate thread session) +- Thread jobs started via `Start-ThreadJob` (separate thread session) -Depending on the context, embedded variables are copied values of the variables -in the caller's scope. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. In thread +sessions, they are passed by reference. ## Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a general type that contains the +original objects properties but not its methods. + +Deserialization maintains type fidelity only for a limited set of known types. +Instances of all other types are emulated. The **PSTypeNames** property +contains the original type name prefixed with **Deserialized**, for example, +**Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter @@ -175,3 +180,4 @@ Invoke-Command -ComputerName S1 -ScriptBlock { [New-PSSession](../New-PSSession.md) +[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md index 2546625c72f3..0e54a14309cd 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -193,7 +193,7 @@ to be defined in the remote session. The `Using` scope modifier is introduced in PowerShell 3.0. -r any script or command that executes out of session, you need the `Using` +For any script or command that executes out of session, you need the `Using` scope modifier to embed variable values from the calling session scope, so that out of session code can access them. The `Using` scope modifier is supported in the following contexts: @@ -201,18 +201,18 @@ the following contexts: - Remotely executed commands, started with `Invoke-Command` using the **ComputerName** or **Session** parameter (remote session) - Background jobs, started with `Start-Job` (out-of-process session) -- Thread jobs, started via `Start-ThreadJob` (separate runspace) +- Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` + (separate thread session) -Depending on the context, embedded variables are copies values or references to -the caller's scope variables. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. For more information, see [about_Remote_Variables](about_Remote_Variables.md). -But for thread jobs receive references to variables. This means it is possible -to modify call scope variables in a different thread. To safely modify -variables requires thread synchronization. +In thread sessions, they are passed by reference. This means it is possible to +modify call scope variables in a different thread. To safely modify variables +requires thread synchronization. For more information see: @@ -637,3 +637,5 @@ Invoke-Command $s { [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) + +[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 03becf4e8a7f..95cd824c4461 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -113,22 +113,28 @@ out of session code can access them. The `Using` scope modifier is supported in the following contexts: - Remotely executed commands, started with `Invoke-Command` using the - **ComputerName** or **Session** parameter (remote session) + **ComputerName**, **HostName**, **SSHConnection** or **Session** parameters + (remote session) - Background jobs, started with `Start-Job` (out-of-process session) -- Thread jobs, started via `Start-ThreadJob` (separate thread session) +- Thread jobs started via `Start-ThreadJob` (separate thread session) -Depending on the context, embedded variables are copied values of the variables -in the caller's scope. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. In thread +sessions, they are passed by reference. ## Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a general type that contains the +original objects properties but not its methods. + +Deserialization maintains type fidelity only for a limited set of known types. +Instances of all other types are emulated. The **PSTypeNames** property +contains the original type name prefixed with **Deserialized**, for example, +**Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md index cc1ce0976057..a67d347b0abb 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -193,26 +193,26 @@ to be defined in the remote session. The `Using` scope modifier is introduced in PowerShell 3.0. -r any script or command that executes out of session, you need the `Using` +For any script or command that executes out of session, you need the `Using` scope modifier to embed variable values from the calling session scope, so that out of session code can access them. The `Using` scope modifier is supported in the following contexts: - Remotely executed commands, started with `Invoke-Command` using the - **ComputerName** or **Session** parameter (remote session) + **ComputerName**, **HostName**, **SSHConnection** or **Session** parameters + (remote session) - Background jobs, started with `Start-Job` (out-of-process session) -- Thread jobs, started via `Start-ThreadJob` (separate runspace) +- Thread jobs started via `Start-ThreadJob` (separate thread session) -Depending on the context, embedded variables are copies values or references to -the caller's scope variables. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. For more information, see [about_Remote_Variables](about_Remote_Variables.md). -But for thread jobs receive references to variables. This means it is possible -to modify call scope variables in a different thread. To safely modify -variables requires thread synchronization. +In thread sessions, they are passed by reference. This means it is possible to +modify call scope variables in a different thread. To safely modify variables +requires thread synchronization. For more information see: @@ -637,3 +637,5 @@ Invoke-Command $s { [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) + +[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob) \ No newline at end of file diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index bf129a97b02d..1e2a64a5818f 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -113,23 +113,29 @@ out of session code can access them. The `Using` scope modifier is supported in the following contexts: - Remotely executed commands, started with `Invoke-Command` using the - **ComputerName** or **Session** parameter (remote session) + **ComputerName**, **HostName**, **SSHConnection** or **Session** parameters + (remote session) - Background jobs, started with `Start-Job` (out-of-process session) - Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` (separate thread session) -Depending on the context, embedded variables are copied values of the variables -in the caller's scope. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. In thread +sessions, they are passed by reference. ## Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a general type that contains the +original objects properties but not its methods. + +Deserialization maintains type fidelity only for a limited set of known types. +Instances of all other types are emulated. The **PSTypeNames** property +contains the original type name prefixed with **Deserialized**, for example, +**Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md index 94a200255c88..649e71b9d485 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -193,27 +193,27 @@ to be defined in the remote session. The `Using` scope modifier is introduced in PowerShell 3.0. -r any script or command that executes out of session, you need the `Using` +For any script or command that executes out of session, you need the `Using` scope modifier to embed variable values from the calling session scope, so that out of session code can access them. The `Using` scope modifier is supported in the following contexts: - Remotely executed commands, started with `Invoke-Command` using the - **ComputerName** or **Session** parameter (remote session) + **ComputerName**, **HostName**, **SSHConnection** or **Session** parameters + (remote session) - Background jobs, started with `Start-Job` (out-of-process session) - Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` - (separate runspace) + (separate thread session) -Depending on the context, embedded variables are copies values or references to -the caller's scope variables. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. For more information, see [about_Remote_Variables](about_Remote_Variables.md). -But for thread jobs receive references to variables. This means it is possible -to modify call scope variables in a different thread. To safely modify -variables requires thread synchronization. +In thread sessions, they are passed by reference. This means it is possible to +modify call scope variables in a different thread. To safely modify variables +requires thread synchronization. For more information see: @@ -639,3 +639,5 @@ Invoke-Command $s { [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) + +[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob) \ No newline at end of file diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index d1b8b9844c64..0f6b9c781c09 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -113,23 +113,29 @@ out of session code can access them. The `Using` scope modifier is supported in the following contexts: - Remotely executed commands, started with `Invoke-Command` using the - **ComputerName** or **Session** parameter (remote session) + **ComputerName**, **HostName**, **SSHConnection** or **Session** parameters + (remote session) - Background jobs, started with `Start-Job` (out-of-process session) - Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` (separate thread session) -Depending on the context, embedded variables are copied values of the variables -in the caller's scope. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. In thread +sessions, they are passed by reference. ## Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a general type that contains the +original objects properties but not its methods. + +Deserialization maintains type fidelity only for a limited set of known types. +Instances of all other types are emulated. The **PSTypeNames** property +contains the original type name prefixed with **Deserialized**, for example, +**Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md index 10dde5bd806f..e0736bdf3b0c 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -193,27 +193,27 @@ to be defined in the remote session. The `Using` scope modifier is introduced in PowerShell 3.0. -r any script or command that executes out of session, you need the `Using` +For any script or command that executes out of session, you need the `Using` scope modifier to embed variable values from the calling session scope, so that out of session code can access them. The `Using` scope modifier is supported in the following contexts: - Remotely executed commands, started with `Invoke-Command` using the - **ComputerName** or **Session** parameter (remote session) + **ComputerName**, **HostName**, **SSHConnection** or **Session** parameters + (remote session) - Background jobs, started with `Start-Job` (out-of-process session) - Thread jobs, started via `Start-ThreadJob` or `ForEach-Object -Parallel` - (separate runspace) + (separate thread session) -Depending on the context, embedded variables are copies values or references to -the caller's scope variables. Out-of-process sessions, such as remote sessions, -background jobs, and workflows, receive values of variables through the -PowerShell serialization system. +Depending on the context, embedded variable values are either independent +copies of the data in the caller's scope or references to it. In remote and +out-of-process sessions, they are always independent copies. For more information, see [about_Remote_Variables](about_Remote_Variables.md). -But for thread jobs receive references to variables. This means it is possible -to modify call scope variables in a different thread. To safely modify -variables requires thread synchronization. +In thread sessions, they are passed by reference. This means it is possible to +modify call scope variables in a different thread. To safely modify variables +requires thread synchronization. For more information see: @@ -639,3 +639,5 @@ Invoke-Command $s { [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) + +[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob) \ No newline at end of file From c9f5b06e7e5e6e803e7c825993882ed5da8182a4 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 18 Mar 2020 07:53:16 -0700 Subject: [PATCH 4/5] more feedback edits --- .../About/about_Remote_Variables.md | 14 +++++++++----- .../About/about_Scopes.md | 19 ++++++++++++++----- .../About/about_Remote_Variables.md | 14 +++++++++----- .../About/about_Scopes.md | 19 ++++++++++++++----- .../About/about_Remote_Variables.md | 14 +++++++++----- .../About/about_Scopes.md | 19 ++++++++++++++----- .../About/about_Remote_Variables.md | 14 +++++++++----- .../About/about_Scopes.md | 19 ++++++++++++++----- 8 files changed, 92 insertions(+), 40 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 20af8098352b..6e6fdcb9efb4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -127,13 +127,17 @@ sessions, they are passed by reference. Remotely executed commands and background jobs run out-of-process. Out-of-process sessions use XML-based serialization and deserialization to make the values of variables available across the process boundaries. The -serialization process converts objects to a general type that contains the +serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. -Deserialization maintains type fidelity only for a limited set of known types. -Instances of all other types are emulated. The **PSTypeNames** property -contains the original type name prefixed with **Deserialized**, for example, -**Deserialized.System.Data.DataTable** +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md index 0e54a14309cd..441f21101928 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -220,11 +220,20 @@ For more information see: #### Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a **PSObject** that contains the +original objects properties but not its methods. + +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ### The AllScope Option diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 95cd824c4461..b7017cf68873 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -128,13 +128,17 @@ sessions, they are passed by reference. Remotely executed commands and background jobs run out-of-process. Out-of-process sessions use XML-based serialization and deserialization to make the values of variables available across the process boundaries. The -serialization process converts objects to a general type that contains the +serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. -Deserialization maintains type fidelity only for a limited set of known types. -Instances of all other types are emulated. The **PSTypeNames** property -contains the original type name prefixed with **Deserialized**, for example, -**Deserialized.System.Data.DataTable** +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md index a67d347b0abb..a70c3b813794 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -220,11 +220,20 @@ For more information see: #### Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a **PSObject** that contains the +original objects properties but not its methods. + +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ### The AllScope Option diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 1e2a64a5818f..727180f989f7 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -129,13 +129,17 @@ sessions, they are passed by reference. Remotely executed commands and background jobs run out-of-process. Out-of-process sessions use XML-based serialization and deserialization to make the values of variables available across the process boundaries. The -serialization process converts objects to a general type that contains the +serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. -Deserialization maintains type fidelity only for a limited set of known types. -Instances of all other types are emulated. The **PSTypeNames** property -contains the original type name prefixed with **Deserialized**, for example, -**Deserialized.System.Data.DataTable** +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md index 649e71b9d485..43a683bfd4f8 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -222,11 +222,20 @@ For more information see: #### Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a **PSObject** that contains the +original objects properties but not its methods. + +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ### The AllScope Option diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 0f6b9c781c09..7878c0c96065 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -129,13 +129,17 @@ sessions, they are passed by reference. Remotely executed commands and background jobs run out-of-process. Out-of-process sessions use XML-based serialization and deserialization to make the values of variables available across the process boundaries. The -serialization process converts objects to a general type that contains the +serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. -Deserialization maintains type fidelity only for a limited set of known types. -Instances of all other types are emulated. The **PSTypeNames** property -contains the original type name prefixed with **Deserialized**, for example, -**Deserialized.System.Data.DataTable** +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ## Using local variables with **ArgumentList** parameter diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md index e0736bdf3b0c..df7ed731521c 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -222,11 +222,20 @@ For more information see: #### Serialization of variable values -Remotely executed commands and background jobs run out-of-process. PowerShell -uses XML-based serialization and deserialization to make the values of -variables available across the process boundaries. The serialization process -converts objects to a **PSObject** type. The **PSObject** is general type that -contains the original objects properties but not its methods. +Remotely executed commands and background jobs run out-of-process. +Out-of-process sessions use XML-based serialization and deserialization to make +the values of variables available across the process boundaries. The +serialization process converts objects to a **PSObject** that contains the +original objects properties but not its methods. + +For a limited set of types, deserialization rehydrates objects back to the +original type. The rehydrated object contains the properties but not the +methods of the original instance. Also, rehydrated certificate types do not +include the private key. + +Instances of all other types are **PSObject** instances. The **PSTypeNames** +property contains the original type name prefixed with **Deserialized**, for +example, **Deserialized.System.Data.DataTable** ### The AllScope Option From 03c734053ed602f2aa3876ed6567ae0569cf3fb4 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 18 Mar 2020 15:15:59 -0700 Subject: [PATCH 5/5] final feedback --- .../About/about_Remote_Variables.md | 8 +++++--- .../5.1/Microsoft.PowerShell.Core/About/about_Scopes.md | 8 +++++--- .../About/about_Remote_Variables.md | 8 +++++--- .../6/Microsoft.PowerShell.Core/About/about_Scopes.md | 8 +++++--- .../About/about_Remote_Variables.md | 8 +++++--- .../7.0/Microsoft.PowerShell.Core/About/about_Scopes.md | 8 +++++--- .../About/about_Remote_Variables.md | 8 +++++--- .../7.1/Microsoft.PowerShell.Core/About/about_Scopes.md | 8 +++++--- 8 files changed, 40 insertions(+), 24 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 6e6fdcb9efb4..b9ae5f9089d3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -131,9 +131,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md index 441f21101928..e5bc8fcba4e4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -227,9 +227,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index b7017cf68873..ce5615f7e457 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -132,9 +132,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md index a70c3b813794..7ea999888b26 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -227,9 +227,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 727180f989f7..fdfeb5ac6444 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -133,9 +133,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md index 43a683bfd4f8..ce59fc2ac697 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -229,9 +229,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 7878c0c96065..9628d797b6bc 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -133,9 +133,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md index df7ed731521c..45f0b92b00d9 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -229,9 +229,11 @@ serialization process converts objects to a **PSObject** that contains the original objects properties but not its methods. For a limited set of types, deserialization rehydrates objects back to the -original type. The rehydrated object contains the properties but not the -methods of the original instance. Also, rehydrated certificate types do not -include the private key. +original type. The rehydrated object is a copy of the original object instance. +It has the type properties and methods. For simple types, such as +**System.Version**, the copy is exact. For complex types, the copy is +imperfect. For example, rehydrated certificate objects do not include the +private key. Instances of all other types are **PSObject** instances. The **PSTypeNames** property contains the original type name prefixed with **Deserialized**, for