New-CimSession (PowerShell 3.0+ )

Create a CIM session. A CIM session is a client-side object representing a connection to a local or remote computer.

When performing a large number of remote operations against the same remote machine, create and reuse a CIM session rather than connecting repeatedly with Get-CimInstance. This can provide a significant performance gain.

      New-CimSession [[-ComputerName] String[]] [[-Credential] PSCredential] [-Name String]
         [-Port UInt32] [-SessionOption CimSessionOptions] [-Authentication PasswordAuthenticationMechanism]
            [-SkipTestConnection] [-OperationTimeoutSec UInt32] [CommonParameters]

      New-CimSession [[-ComputerName] String[]] [-CertificateThumbprint String] [-Name String]                                        
         [-Port UInt32] [-SessionOption CimSessionOptions]
            [-SkipTestConnection] [-OperationTimeoutSec UInt32] [CommonParameters]

   -Authentication PasswordAuthenticationMechanism
       The authentication type used for the user’s credentials. psdx_paramvaluesDefault, Digest, Negotiate, 
       Basic, Kerberos, NtlmDomain and CredSsp.

       You cannot use the NtlmDomain authentication type for connection to the local computer. CredSSP authentication 
       is available only in firstref_vista, firstref_longhorn, and later versions of Windows.

       Caution: Credential Security Service Provider (CredSSP) authentication, in which the user’s credentials are 
       passed to a remote computer to be authenticated, is designed for commands that require authentication on more 
       than one resource, such as accessing a remote network share. This mechanism increases the security risk of the 
       remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to 
       control the network session.

   -CertificateThumbprint String
       The digital public key certificate (X.509) of a user account that has permission to perform this action.
       Enter the certificate thumbprint of the certificate.

       Certificates are used in client certificate-based authentication.
       They can be mapped only to local user accounts; they do not work with domain accounts.

       To get a certificate thumbprint, use the Get-Item or Get-ChildItem cmdlets in the wps_1 Certificate provider. 
       For more information about using the wps_2 Certificate provider, type Get-Help Certificate, or see TechNet.

   -ComputerName String[]
       The name of the computer to which to create the CIM session.
       Specify either a single computer name, or multiple computer names separated by a comma. 
       When -ComputerName is specified the WS-Management (WS-Man) protocol will be used.

       If ComputerName is not specified, a CIM session to the local computer is created.
       You can specify the value for computer name in one of the following formats: 
         One or more NetBIOS names              
         One or more IP addresses 
         One or more fully qualified domain names.

       If the computer is in a different domain than the user, you must specify the fully qualified domain name.
       You can also pass a computer name (in quotes) to New-CimSession by using the pipeline.

   -Credential PSCredential
       A user account that has permission to perform this action. If Credential is not specified, the 
       current user account is used.

       Specify the value for Credential by using one of the following formats: 

       A user name: "User01" 
       A domain name and a user name: "Domain01\User01"                   
       A user principal name: ""                   
       A PSCredential object, such as one returned by the Get-Credential cmdlet.

       When you type a user name, you are prompted for a password.
   -Name String
       A friendly name for the CIM session.

       You can use the name to refer to the CIM session when using other cmdlets, such as the Get-CimSession cmdlet. 
       The name is not required to be unique to the computer or the current session.
   -OperationTimeoutSec UInt32
       Duration for which the cmdlet waits for a response from the server.
       By default, the value of this parameter is 0, which means that the cmdlet uses the default timeout value for 
       the server.

       If the OperationTimeoutSec parameter is set to a value less than the robust connection retry timeout of 3 
       minutes, network failures that last more than the value of the OperationTimeoutSec parameter are not 
       recoverable, because the operation on the server times out before the client can reconnect.

   -Port UInt32
       Specifies the network port on the remote computer that is used for this connection. To connect to a remote 
       computer, the remote computer must be listening on the port that the connection uses. The default ports are 
       5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS).

       Before using an alternate port, you must configure the WinRM listener on the remote computer to listen at that 
       port. Use the following commands to configure the listener: 
         1. winrm delete winrm/config/listener?Address=*+Transport=HTTP 

         2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="port-number"}
       Do not use the Port parameter unless you must. The port setting in the command applies to all computers or 
       sessions on which the command runs. An alternate port setting might prevent the command from running on all 

   -SessionOption CimSessionOptions
       Sets advanced options for the new CIM session. Enter the name of a CimSessionOption object created by using 
       the New-CimSessionOption cmdlet.

       By default, the New-CimSession cmdlet establishes a connection with a remote WS-Management endpoint for two 
       reasons: to verify that the remote server is listening on the port number that is specified by using the Port 
       parameter, and to verify the specified account credentials. The verification is accomplished by using a 
       standard WS-Identity operation. You can add the SkipTestConnection switch parameter if the remote 
       WS-Management endpoint cannot use WS-Identify, or if you want to reduce some data transmission time.

Standard Aliases for New-CIMSession: ncms

New-CIMSession returns a CIM session object that can be used by all other CIM cmdlets.

To connect to a remote machine, pass credentials (a secure password string) obtained with Get-Credential.

The CIM session contains information about the connection, such as ComputerName, the protocol used for the connection, session ID and instance ID.


Create a CIM session with default options, a DCOM session to the local computer:

PS C:\> New-CimSession

Create a CIM session to a specific computer, store in a variable for re-use:

PS C:\> $session = New-CimSession -ComputerName computer64

PS C:\> Get-CimInstance –ClassName CIM_ComputerSystem –CimSession $session

Create a CIM session to multiple computers:

PS C:\> $all = New-CimSession -ComputerName Server64,Server65,Server66

Reboot all those machines:

PS C:\> Invoke-CimMethod –ClassName Win32_OperatingSystem –MethodName Reboot –CimSession $all

Create a CIM session with a friendly name, to easily refer to the session in other CIM cmdlets, for example, Get-CimSession:

PS C:\> New-CimSession -ComputerName Server64,Server65 -Name FileServers

PS C:\> Get-CimSession -Name File*

Create a CIM session to a computer using a PSCredential object, create the PSCredential object with Get-Credential:

PS C:\> New-CimSession -ComputerName Server64 -Credential $cred -Authentication Negotiate

Create a CIM session using DCOM:

PS C:\> $so = New-CimSessionOption -Protocol DCOM
PS C:\> New-CimSession -ComputerName Server64 -SessionOption $so

“There are two ways of spreading light: to be the candle or the mirror that reflects it” ~ Edith Wharton

Related PowerShell Cmdlets

Get-CimSession - Get current CIM session objects.
Get-CimInstance - Get a managed resource (storage, network, software etc.)
Invoke-CimMethod - Invoke a method of a CIM class or CIM instance.
New-CimSessionOption - Specify advanced options for New-CimSession.
Remove-CimSession - Remove one or more CIM session objects.

Copyright © 1999-2024
Some rights reserved