While working with remote computers with PowerShell, you'll come across many scenarios where you may want to use local variables or data in a remote session. But when you try to use a local variable in a remote session, it may not work or may throw an error because the local variable doesn't exist in the remote session.

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

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

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

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

The $using scope modifier

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

Subscribe to 4sysops newsletter!

$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

Changing scope in PSSession


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.

  1. MikeC 5 years ago

    This is great.  Thanks. I have always passed them using -ArgumentList  great tip!  Thanks.

  2. Rajkumar 2 years ago

    I want to trigger the powershell script which is available in server (x), Is there any way to trigger it?

    • Leos Marek (Rank 4) 2 years ago

      You want to use invoke-command to call a script located on network share? You will have a double-hop issue there…

      Anyway, why would you need something like that?

Leave a reply

Your email address will not be published.


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account