PowerShell Logo Small

New-PSSession



This is the built-in help made by Microsoft for the command 'New-PSSession', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates a persistent connection to a local or remote computer.

SYNTAX


New-PSSession [[-ComputerName] [<String[]>]] [-ApplicationName [<String>]] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest
| Kerberos}] [-CertificateThumbprint [<String>]] [-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-EnableNetworkAccess] [-Name [<String[]>]] [-Port [<Int32>]]
[-SessionOption [<PSSessionOption>]] [-ThrottleLimit [<Int32>]] [-UseSSL] [<CommonParameters>]
New-PSSession [-ConnectionUri] <Uri[]> [-AllowRedirection] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint [<String>]] [-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-EnableNetworkAccess] [-Name [<String[]>]] [-SessionOption
[<PSSessionOption>]] [-ThrottleLimit [<Int32>]] [<CommonParameters>]
New-PSSession [[-Session] [<PSSession[]>]] [-EnableNetworkAccess] [-Name [<String[]>]] [-ThrottleLimit [<Int32>]] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The New-PSSession cmdlet creates a Windows PowerShell session (PSSession) on a local or remote computer. When you create a PSSession, Windows PowerShell establishes a
persistent connection to the remote computer.


Use a PSSession to run multiple commands that share data, such as a function or the value of a variable. To run commands in a PSSession, use the Invoke-Command cmdlet. To
use the PSSession to interact directly with a remote computer, use the Enter-PSSession cmdlet. For more information, see about_PSSessions
(http://go.microsoft.com/fwlink/?LinkID=135181).


You can run commands on a remote computer without creating a PSSession by using the ComputerName parameters of Enter-PSSession or Invoke-Command. When you use the
ComputerName parameter, Windows PowerShell creates a temporary connection that is used for the command and is then closed.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289596
Connect-PSSession
Disconnect-PSSession
Enter-PSSession
Exit-PSSession
Get-PSSession
Invoke-Command
Receive-PSSession
Remove-PSSession
about_PSSessions
about_Remote

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

PS C:\>$s = New-PSSession



This command creates a new PSSession on the local computer and saves the PSSession in the $s variable.

You can now use this PSSession to run commands on the local computer.










-------------------------- EXAMPLE 2 --------------------------

PS C:\>$Server01 = New-PSSession -ComputerName Server01



This command creates a new PSSession on the Server01 computer and saves it in the $Server01 variable.

When creating multiple PSSessions, assign them to variables with useful names. This will help you manage the PSSessions in subsequent commands.










-------------------------- EXAMPLE 3 --------------------------

PS C:\>$s1, $s2, $s3 = New-PSSession -ComputerName Server1,Server2,Server3



This command creates three new PSSessions, one on each of the computers specified by the ComputerName parameter.

The command uses the assignment operator (=) to assign the new PSSessions to an array of variables: $s1, $s2, $s3. It assigns the Server01 PSSession to $s1, the Server02
PSSession to $s2, and the Server03 PSSession to $s3.

When you assign multiple objects to an array of variables, Windows PowerShell assigns each object to a variable in the array respectively. If there are more objects than
variables, all remaining objects are assigned to the last variable. If there are more variables than objects, the remaining variables are empty (null).










-------------------------- EXAMPLE 4 --------------------------

PS C:\>New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12



This command creates a new PSSession on the Server01 computer that connects to server port 8081 and uses the SSL protocol. The new PSSession uses an alternate session
configuration called "E12".

Before setting the port, you must configure the WinRM listener on the remote computer to listen on port 8081. For more information, see the description of the Port parameter.










-------------------------- EXAMPLE 5 --------------------------

PS C:\>New-PSSession -Session $s -Credential Domain01\User01



This command creates a new PSSession with the same properties as an existing PSSession. You can use this command format when the resources of an existing PSSession are
exhausted and a new PSSession is needed to offload some of the demand.

The command uses the Session parameter of New-PSSession to specify the PSSession saved in the $s variable. It uses the credentials of the Domain1\Admin01 user to complete
the command.










-------------------------- EXAMPLE 6 --------------------------

PS C:\>$global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01



This example shows how to create a PSSession with a global scope on a computer in a different domain.

By default, PSSessions created at the command line are created with local scope and PSSessions created in a script have script scope.

To create a PSSession with global scope, create a new PSSession and then store the PSSession in a variable that is cast to a global scope. In this case, the $s variable is
cast to a global scope.

The command uses the ComputerName parameter to specify the remote computer. Because the computer is in a different domain than the user account, the full name of the
computer is specified along with the credentials of the user.










-------------------------- EXAMPLE 7 --------------------------

PS C:\>$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50



This command creates a PSSession on each of the 200 computers listed in the Servers.txt file and it stores the resulting PSSession in the $rs variable. The PSSessions have a
throttle limit of 50.

You can use this command format when the names of computers are stored in a database, spreadsheet, text file, or other text-convertible format.










-------------------------- EXAMPLE 8 --------------------------

PS C:\>$s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01



This command creates a PSSession on the Server01 computer and stores it in the $s variable. It uses the URI parameter to specify the transport protocol, the remote computer,
the port, and an alternate session configuration. It also uses the Credential parameter to specify a user account with permission to create a session on the remote computer.










-------------------------- EXAMPLE 9 --------------------------

PS C:\>$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
PS C:\>Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob



These commands create a set of PSSessions and then run a background job in each of the PSSessions.

The first command creates a new PSSession on each of the computers listed in the Servers.txt file. It uses the New-PSSession cmdlet to create the PSSession. The value of the
ComputerName parameter is a command that uses the Get-Content cmdlet to get the list of computer names the Servers.txt file.

The command uses the Credential parameter to create the PSSessions with the permission of a domain administrator, and it uses the ThrottleLimit parameter to limit the
command to 16 concurrent connections. The command saves the PSSessions in the $s variable.

The second command uses the AsJob parameter of the Invoke-Command cmdlet to start a background job that runs a "Get-Process PowerShell" command in each of the PSSessions in
$s.

For more information about background jobs, see about_Jobs (http://go.microsoft.com/fwlink/?LinkID=113251) and about_Remote_Jobs
(http://go.microsoft.com/fwlink/?LinkID=135184).










-------------------------- EXAMPLE 10 --------------------------

PS C:\>New-PSSession -ConnectionURI https://management.exchangelabs.com/Management



This command creates a new PSSession that connects to a computer that is specified by a URI instead of a computer name.










-------------------------- EXAMPLE 11 --------------------------

PS C:\>$so = New-PSSessionOption -SkipCACheck
PS C:\>New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01



This example shows how to create a session option object and use the SessionOption parameter.

The first command uses the New-PSSessionOption cmdlet to create a session option. It saves the resulting SessionOption object in the $so parameter.

The second command uses the option in a new session. The command uses the New-PSSession cmdlet to create a new session. The value of the SessionOption parameter is the
SessionOption object in the $so variable.