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..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 @@ -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) 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..e5bc8fcba4e4 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,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) \ 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 8a9df50c0241..ce5615f7e457 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) @@ -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) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md index 56df7b1249d5..7ea999888b26 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,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) \ 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 bdcf4eb5a41d..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 @@ -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 @@ -105,14 +105,50 @@ $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` 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. 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 +180,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..ce59fc2ac697 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,54 @@ 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` 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) +- [ForEach-Object](../ForEach-Object.md#notes) + +#### 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 +650,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 72dee3240a7d..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 @@ -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 @@ -105,14 +105,50 @@ $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` 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. 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 +180,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..45f0b92b00d9 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,54 @@ 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` 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) +- [ForEach-Object](../ForEach-Object.md#notes) + +#### 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 +650,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