How to Leverage Reusable PS Remoting Sessions in your Scripts

PowerShell Remoting (PS Remoting) empowers you to run PowerShell code on remote machines as if you were sitting right in front of them. This tutorial will walk you through the creation and management of PS sessions, allowing you to execute commands on one or thousands of machines efficiently.

Reusable sessions are key to maximizing PS Remoting’s potential. By establishing a persistent connection, you can avoid the overhead of repeatedly authenticating and setting up new sessions. This approach improves performance and simplifies script design.

To follow along, you’ll need a PowerShell console and at least one remote computer accessible via PS Remoting. Let’s dive in!

Creating a New PowerShell Session

The New-PSSession cmdlet is your gateway to the remote machine. We’ll store the session object in a variable for easy reference

$session = New-PSSession -ComputerName SRV2

This command creates a session with the computer named “SRV2.” You can substitute the actual name of your remote machine.

Both of my computers are on the same Active Directory domain so no additional authentication is required.

If you look at the $session variable, you’ll see that PS Remoting using the WSman protocol for communication, the state and other valuable info.

Listing Active Sessions

Want to see what sessions are active? Get-PSSession provides a list

Get-PSSession

This gives you an overview of the open sessions, including the computer names they’re connected to. You should see the same output as inspecting the $session variable since we only have a single session open.

With a session established, you can send commands using Invoke-Command.

Invoke-Command -Session $session -ScriptBlock { hostname }

-Session $session specifies the session we created earlier and ScriptBlock { hostname }defines a block of code to run on the remote machine. In this case, we’re simply asking for the computer’s hostname.

The output will confirm that you’re indeed seeing the hostname of the remote machine.

Storing and Retrieving Variables in a Session

Sessions can maintain state. Let’s create a variable on the remote machine and retrieve it later:

Invoke-Command -Session $session -ScriptBlock { $foo = 'Please be here next time' }

Here I’m defining a variable inside of the scriptblock which passes that code to the remote machine and executes under the session context. Since I’ve saved the session, I can reference that same session again and access the value of the variable.

Invoke-Command -Session $session -ScriptBlock { $foo }

Notice how the second Invoke-Command can access the $foo variable we defined earlier.

Creating a Function to Use a Shared Session

Let’s say you have a function that removes a folder on a local computer. I’m just using this as simple example; the function could do anything.

function Remove-FileFolder {
	param($Path)
	Remove-Item -Path $Path
}

Now, perhaps, you’d like this function to perform the same task on a remote computer. One way to do this is by using a PS Remoting session.

To do that, you could add a Session parameter to the function.

function Remove-FileFolder {
	param(
		[Parameter(Mandatory)]
		[string]$Path,
		
		[Parameter(Mandatory)]
		[System.Management.Automation.Runspaces.PSSession]$Session
	)
}

You should always define a type for parameters. To get the session type, you can pipe the session object created earlier to Get-Member.

$session | Get-Member

You must then refactor the code to use Invoke-Command to execute the removal remotely.

Invoke-Command -Session $Session {	Remove-Item -Path $using:Path }

Notice the $using construct? That allows you to pass the $Path variable that’s defined locally to the remote computer. Otherwise, PowerShell wouldn’t know what the $Path variable would be while in the remote session context.

Once you’ve made your changes, the function would look like this:

function Remove-FileFolder {
	param(
		[Parameter(Mandatory)]
		[string]$Path,
		
		[Parameter(Mandatory)]
		[System.Management.Automation.Runspaces.PSSession]$Session
	)
	
	Invoke-Command -Session $Session {	Remove-Item -Path $using:Path }
}

You now have a function that will execute code on a remote computer! And, since you’re using a reusable session, you can also define code and then reference it later!