Share this post: This is part of an ongoing blog series by Adam Gordon. Adam will show you how to use each PowerShell command each week. Adam will be covering New-PSSession this week.
When should you use New-PSSession
The New-PSSession cmdlet creates PowerShell sessions (PSSessions) on a local computer or remote computer. PowerShell establishes an ongoing connection to the remote computer when you create a PSSession.
Multiple commands can be run in a PSSession. They share data such as the value of a variable or a function. Use the Invoke Command cmdlet to run commands in a PSSession. Use the Enter-PSSession cmdlet to interact with remote computers using the PSSession.
You can execute commands on a remote computer by using the –ComputerName parameters of Invoke-Command or Enter-PSSession. PowerShell creates an indefinite connection to the remote computer when you use the parameter -ComputerName. This temporary connection is used for the command, and then it is closed.
Secure Shell (SSH), which is available with PowerShell 6.0, can be used to establish a connection to and to create a session on remote computers. If SSH is available on the local machine and the remote computer has a PowerShell SSH pointpoint, then you can use this to establish a connection. An SSH-based PowerShell remote session can be used on multiple platforms (Windows and Linux, as well as macOS). You can use the -HostName parameter or -SSHConnection parameter to specify the remote computer as well as the connection information.
NOTE: If you are using WSMan remote from a Linux/macOS client with a HTTPS endingpoint, the server certificate may not be trusted (e.g. a self-signed cert). To establish the connection, you must provide a session option that includes -SkipCACheck or -SkipCNCheck. This should only be done if you have access to the server certificate and the network connection to your target system.
What version of PowerShell do I use?
Get the PowerShell Version for your machine
This command displays the PowerShell version information for your machine.
How to use New-PSSession?
Create a session from a remote computer
$ITPTV01 = New-PSSession -ComputerName ITPTV01
This command creates a new PSSession for the ITPTV01 computer, and saves it to the $ITPTV01 variable.
Assign multiple PSSession objects to variables with meaningful names. This will allow you to manage PSSession objects with subsequent commands.
You can create sessions on multiple computers.
$s1, $s2, $s3 = New-PSSession -ComputerName ITPTV01,ITPROTV02,ITPtv03
This command creates three PSSession object PSSession objects on each computer specified by the –ComputerName parameter.
The assignment operator (=), which is used to assign new PSSession objects and variables to variables, $s1, $s2, and $s3, is used by the command. It assigns the ITPTV01 PSSession at $s1, the ITPROTV02 PSSession at $s2, and ITPtv03 PSSession at $s3.
PowerShell assigns multiple objects to a set of variables. If there are more variables than objects, all objects are assigned to that variable. If there are more variables that objects, the variables remaining are empty (null).
Create a session using a specific port:
New-PSSession -ComputerName ITPTV01 -Port 8081 -UseSSL
This command creates a new PSSession for the ITPTV01 computer. It connects to server port 808 and uses the SSL protocol.
Before you can set the port, configure WinRM on the remote computer so that it can listen to port 8081.
You can create a session in a different domain with a global scope.
$global:s = New-PSSession -ComputerName ITPTV1.ITPRO.TV -Credential ITPROTVPSHELL\Adam
PSSession object created at the command-line have local scope, while PSSession object created in a script has script scope.
Create a new PSSession to create a PSSession that has global scope. Then store the PSSession into a variable that has global scope. In this example, the $s variable has a global scope.
To specify the remote computer, the command uses the parameter -ComputerName. The computer is located in a different domain to the user account. Therefore, the full name of that computer is included with the credentials.
You can create sessions for multiple computers
$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50
This command creates a PSSession for each computer listed in the Servers.txt files and stores the resulting PSSession into the $rs variable. The throttle limit for PSSession objects is 50
NOTE: This command format can be used when names of computers are stored either in a text file, spreadsheet, text file or other text-convertible format.
Use a URI to create a session:
$s = New-PSSession -URI http://ITPTV01:91/NewSession -Credential ITPROTV\Adam
This command creates an PSSession on Server01 computer