Using a local variable in a remote PowerShell session

• Author
• Recent Posts

Prateek Singh

Prateek Singh is an infrastructure developer, an avid PowerShell blogger, and a community contributor. In 2017, FeedSpot recognized his blog RidiCurious.com as among the "Top 50 PowerShell blogs in the world." All of his PowerShell projects and modules are open-sourced at GitHub, and you can reach out to him on Twitter at @SinghPrateik.

Latest posts by Prateek Singh (see all)

• Create a custom role with Azure role-based access control (Azure RBAC) using PowerShell - Wed, Jan 20 2021
• Step by step Deploying Docker Container to Azure using Azure CLI - Wed, Sep 2 2020
• Install Docker offline on Windows Server 2016 - Thu, Dec 6 2018

To overcome this gap, PowerShell provides three methods to pass local variables to remote sessions. You can use them with Invoke-Command and New-PSSession:

1. The $args automatic variable
2. The $using scope modifier
3. The param() block

Local variable in a remote session

Make sure to get the user credentials and choose a computer name before using the commands in the following methods.

Using the $args automatic variable

The $args variable is an automatic variable that contains an array of the undeclared parameters or parameter values passed to a function or a scriptblock. You can access the parameters passed to the scriptblock just like elements of an array.

The first parameter passed to the scriptblock is $args[0], the second is $args[1], and so on. That means we can use $args in the scriptblock and run it remotely via the Invoke-Command cmdlets. We can pass the parameters through the -ArgumentList parameter like in the following example:

$a = 1
$b = 2

# Using the $args automatic variable 
Invoke-Command -ComputerName $server `
               -ScriptBlock {"Sum:{0}" -f $($args[0]+$args[1])} `
               -Credential $creds -ArgumentList $a, $b

Using the $args automatic variable

Parameterized scriptblocks using param()

You can use param() blocks inside a function to accept parameters, but the only difference between a function and a scriptblock is that a function is a named scriptblock. That means that just like in a function, we can use a param() block in a scriptblock. Then we will use this scriptblock with the Invoke-Command cmdlet and pass parameters through the -ArgumentList.

$a = 1
$b = 2

# using the param() block in the scriptblock
Invoke-Command -ComputerName $server `
               -ScriptBlock {param($num1,$num2) "Sum:{0}" -f ($num1+$num2)} `
               -Credential $creds -ArgumentList $a,$b

Using a parameterized scriptblock

The $using scope modifier

You can use local variables in remote sessions, but you must indicate that the variable is defined in the local session. Since Windows PowerShell 3.0, you can use the $using scope modifier to indicate that the variable defined in remote session is also defined in the local session, like in the following example:

$a = 1
$b = 2

# with the $using scope modifier 
Invoke-Command -ComputerName $server `
               -ScriptBlock {"Sum:{0}" -f $($using:a+$using:b)} `
               -Credential $creds

The $using scope modifier

You can also change the scope of the local variable in PSSessions with the $using scope modifier:

$a = 2
$b = 7

$S = New-PSSession -ComputerName $server -Credential $creds
Invoke-Command -Session $s -ScriptBlock {"Sum:{0}" -f $($using:a+$using:b)}

Changing scope in PSSession

Conclusion

In PowerShell 2, you could use local variables in remote PowerShell sessions by passing arguments to the remote scriptblock and capturing them inside the scriptblock with either the $args automatic variable or param() blocks. But since Windows PowerShell v3, we can use the scope modifier $using to change the scope of local variables. This makes them work in the remote session very easily without passing any arguments and capturing the arguments or parameters.