Add more information about 'using' scope modifier (#5596)

* add more information about 'using' scope modifier

* editorial feedback

* feedback edits

* more feedback edits

* final feedback

Co-authored-by: Jos Koelewijn <[email protected]>

Author: sdwheeler

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
@@ -105,14 +105,48 @@ $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 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 thread session)
+
+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.
+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 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
+example, **Deserialized.System.Data.DataTable**
+
+## 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,8 +178,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](/powershell/module/ThreadJob/Start-ThreadJob)

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,52 @@ 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.
+
+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)
+- 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 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).
 
+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:
+
+- [Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md)
+
+#### Serialization of variable values
+
+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 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
+example, **Deserialized.System.Data.DataTable**
+
 ### The AllScope Option
 
 Variables and aliases have an **Option** property that can take a value of
@@ -606,3 +648,5 @@ Invoke-Command $s {
 [about_Functions](about_Functions.md)
 
 [about_Script_Blocks](about_Script_Blocks.md)
+
+[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob)

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)
@@ -105,14 +105,49 @@ $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 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**, **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)
+
+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.
+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 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
+example, **Deserialized.System.Data.DataTable**
+
+## 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,8 +179,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)

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,52 @@ 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.
+
+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**, **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)
+
+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).
 
+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:
+
+- [Start-ThreadJob](../../ThreadJob/Start-ThreadJob.md)
+
+#### Serialization of variable values
+
+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 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
+example, **Deserialized.System.Data.DataTable**
+
 ### The AllScope Option
 
 Variables and aliases have an **Option** property that can take a value of
@@ -606,3 +648,5 @@ Invoke-Command $s {
 [about_Functions](about_Functions.md)
 
 [about_Script_Blocks](about_Script_Blocks.md)
+
+[Start-ThreadJob](/powershell/module/ThreadJob/Start-ThreadJob)