61PSSessions

SENDINGASCRIPTINSTEADOFACOMMAND

Our example of Invoke-Command showed how to send just one command, or even a few commands separated by semicolons. For example, to run a command that’s located in a module, you first need to load the module:

PS C:\> Invoke-Command –ScriptBlock { Import-Module ActiveDirectory; ➥ Get-ADUser –filter * } –ComputerName WINDC1

PowerShell v3 and v4 autoloads modules by default, though you won’t see them using Get-Module–ListAvailable until you’ve used them. Forcing the module to load is required for PowerShell v2 and does no harm in v3 or later. In a mixed environment, it’s essential. The module has to be available on the remote machine. Invoke-Command can also send an entire script file, if you prefer. The file path and name are provided to the –FilePath parameter, which you’d use in place of –ScriptBlock. PowerShell will read the contents of the file from the local machine and transmit them over the network—the remote machines don’t need direct access to the file itself.

10.4

PSSessions

So far, your use of Remoting has been ad hoc. You’ve allowed PowerShell to create the connection, it’s run your commands, and then it closes the connection. Without real- izing it, you’ve been creating a temporary PowerShell session, or PSSession. A PSSession represents the connection between your computer and a remote one. Some overhead is involved in setting up a connection and then closing it down, and if you plan to connect to the same computer several times within a period of time, you may want to create a persistent connection to avoid that overhead.

Persistent connections have another advantage: They represent a running copy of PowerShell on a remote machine. Using the ad hoc Remoting that we’ve shown you so far, every single command you send runs in a new, fresh copy of the shell. With a per- sistent connection, you could continue to send commands to the same copy of Power- Shell, and the results of those commands—such as importing modules—would remain in effect until you closed the connection.

10.4.1 Creating a persistent session

The New-PSSession command sets up one or more new sessions. You might want to assign these session objects to a variable so that you can easily refer to them in the future:

PS C:\> $win8 = New-PSsession -ComputerName win8

PS C:\> $domaincontrollers = New-PSsession -ComputerName win8,windc1

Here, you’ve created a variable, $win8, that contains a single session object, and a vari- able, $domaincontrollers, that contains two session objects.

NOTE New-PSSession offers the same options for using alternate credentials, using SSL, and using port numbers as Enter-PSSession and Invoke-Command.

10.4.2 Using a session

Both Invoke-Command and Enter-PSSession can use an already-open session object. Provide the object (or objects) to the commands’ –Session parameter, instead of using the –ComputerName parameter. For example, to initiate a 1-to-1 connection to a computer, use this:

PS C:\> Enter-PSSession -Session $win8 [win8]: PS C:\Users\Administrator\Documents>

Be careful to pass only a single session to Enter-PSSession; if you give it multiple objects, the command can’t function properly. Invoke-Command, though, can accept multiple sessions:

PS C:\> Invoke-Command -Session $domaincontrollers -ScriptBlock { ➥ get-eventlog -LogName security -Newest 50 }

As we mentioned, it’s a lot easier to work with sessions if you keep them in a variable. That isn’t mandatory, though, because you can use Get-PSSession to retrieve ses- sions. For example, if you have an open session to a computer named WINDC1, you can retrieve the session and connect to it like this:

PS C:\> Enter-PSSession –Session (Get-PSSession –computername WINDC1)

The parenthetical Get-PSSession runs first, returning its session object to the –Ses- sion parameter of Enter-PSSession. If you have multiple sessions open to the same computer, the command will fail.

10.4.3 Managing sessions

Session objects will remain open and available for quite some time by default; you can configure a shorter idle timeout if you want. You can display a list of all sessions, and their status, by running Get-PSSession with no parameters:

PS C:\> Get-PSSession

Id Name ComputerName State ConfigurationName Ava ila bil ity -- ---- --- --- --- --- 6 Session6 win8 Opened Microsoft.PowerShell ble 7 Session7 win8 Opened Microsoft.PowerShell ble

Note that the output includes both the state (Opened, in this case) and availability (Available, although our output here is a bit truncated). You can also see the name of the endpoint that the session is connected to—Microsoft.PowerShell in both instances in this example. One reason you might maintain multiple connections to a single remote machine is to connect to different endpoints—perhaps, for example, you might want a connection to both a 64-bit and a 32-bit PowerShell session.

When you’ve finished with a session, you can close it to free up resources. For example, to close all open sessions, use this:

63