How to use variables in remote commands in PowerShell

Variables are a commonly used feature of programming languages, and PowerShell is no exception. But variables can get a bit weird when you try to use them with remote commands. Let’s clear up the confusion and highlight the correct way to use your local variables in remote commands in PowerShell. It’s super easy, it beats walking to a desk to run the command locally, and you get to avoid users. It’s a classic win-win-win situation.

What is a variable in PowerShell?

As with other programming languages, variables in PowerShell are used to store information. You can think of a variable as a type of container.

So, what kind of information can you contain in a variable? Well, pretty much anything. Variables can contain objects, values, commands, arrays, paths, calculations, text strings, results, and other variables. You can even declare a variable and just leave it empty inside — kind of like me (queue The Sound of Silence).

How do you set a variable in PowerShell?

Setting a variable is super easy, and if you’ve ever seen a PowerShell script, chances are, you’ve seen a variable being set. To set a variable, use the dollar sign ($) directly followed by the name you want to assign the variable and an equal symbol (=). The name can be anything you want, though you should avoid using preexisting automatic variable names. You can even include spaces and special characters in your variable names, but doing so is frowned upon.

After you’ve named your variable, you need to assign it some type of value. Here's an example script where I set an assortment of variables and return their values.

In this example, we have a variety of variables being declared. We have text strings, integers, calculations using variables, an empty variable, objects that have been returned from a command, and an array of items. At the end of the script, I use the Get-Variable command to return all the assigned values of the variables. You’ll notice that the variable $e is not returned because its value is automatically set to $null since we left it empty.

The problem with variables and remote commands

The problem that people frequently run into is that locally defined variables aren’t passed to remote commands like Invoke-Command or New-PSSession. Here’s what happens when I try to call a locally defined variable from a remote command:

In this example, I’ve set $MyVariable to a value of 42. Then, I output the value of the variable both locally and in the remote command. In the results, you can see that locally $MyVariable has a value of 42, but in the remote command $MyVariable returned empty.

One way around this issue is to define the variable in the remote command. For example:

While this approach solves the problem, there are a couple of issues with it. First, having multiple variables that share the same name in a script is generally frowned upon and makes your script harder to read. Second, even if you use a different variable name, now you have two variables that should contain the same information that you have to maintain. That’s just extra work, and nobody likes extra work.

You can also pass local variables through the -ArgumentList parameter. This method is handy if backwards compatibility is a concern, but even it can make your scripts more difficult to digest.

Thankfully, there’s a better way.

How to pass (or use) variables in remote commands

The best way to use variables with remote commands is with the Using: scope modifier. This modifier wasn’t available prior to PowerShell 3.0, but considering PowerShell 3.0 was released in 2012, it’s safe to assume most people have access to it nowadays.

To implement the Using: scope modifier, simply replace the variable name in your remote command with $Using:<variable_name>. If my variable name were $ComputerName, I would replace it with $Using:ComputerName in my remote command.

Here’s an example leveraging the Using: modifier.

As you can see, I didn’t have to use any weird naming conventions or update multiple variables. Everything is still easy to read and tied to the initial variable I created, which makes updating the script in the future very easy. Most importantly, I didn’t have to use any PowerShell Kung Fu to make it work. While I’m not opposed to some Kung Fu every now and then, I’d rather limit it to my beloved collection of Jackie Chan movies.