Edit

Share via

New-CimSessionOption

Module:
CimCmdlets Module

Specifies advanced options for the New-CimSession cmdlet.

Syntax

ProtocolTypeSet (Default) 

New-CimSessionOption
    [-Protocol] <ProtocolType>
    [-UICulture <CultureInfo>]
    [-Culture <CultureInfo>]
    [<CommonParameters>]

WSManParameterSet 

New-CimSessionOption
    [-NoEncryption]
    [-SkipCACheck]
    [-SkipCNCheck]
    [-SkipRevocationCheck]
    [-EncodePortInServicePrincipalName]
    [-Encoding <PacketEncoding>]
    [-HttpPrefix <Uri>]
    [-MaxEnvelopeSizeKB <UInt32>]
    [-ProxyAuthentication <PasswordAuthenticationMechanism>]
    [-ProxyCertificateThumbprint <String>]
    [-ProxyCredential <PSCredential>]
    [-ProxyType <ProxyType>]
    [-UseSsl]
    [-UICulture <CultureInfo>]
    [-Culture <CultureInfo>]
    [<CommonParameters>]

DcomParameterSet 

New-CimSessionOption
    [-Impersonation <ImpersonationType>]
    [-PacketIntegrity]
    [-PacketPrivacy]
    [-UICulture <CultureInfo>]
    [-Culture <CultureInfo>]
    [<CommonParameters>]

Description

This cmdlet is only available on the Windows platform.

The New-CimSessionOption cmdlet creates an instance of a CIM session options object. You use a CIM session options object as input to the New-CimSession cmdlet to specify the options for a CIM session.

This cmdlet has two parameter sets, one for WsMan options and one for Distributed Component Object Model (DCOM) options. Depending on which parameters you use, the cmdlet returns either an instance of DCOM session options or returns WsMan session options.

Examples

Example 1: Create a CIM session options object for DCOM

This example creates a CIM session options object for the DCOM protocol and stores it in a variable named $so. The contents of the variable are then passed to the New-CimSession cmdlet. New-CimSession then creates a new CIM session with the remote server named Server01, using the options defined in the variable.

$so = New-CimSessionOption -Protocol Dcom
New-CimSession -ComputerName Server01 -SessionOption $so

Example 2: Create a CIM session options object for WsMan

This example creates a CIM session options object for the WsMan protocol. The object contains configuration for the authentication mode of Kerberos specified by the ProxyAuthentication parameter, the credentials specified by the ProxyCredential parameter, and specifies that the command is to skip the CA check, skip the CN check, and use SSL.

$option = @{
    ProxyAuthentication = 'Kerberos'
    ProxyCredential = $cred
    SkipCACheck = $true
    SkipCNCheck = $true
    UseSsl = $true
}
New-CimSessionOption @option

Example 3: Create a CIM session options object with the culture specified

New-CimSessionOption -Culture fr-FR -Protocol Wsman

This example specifies the culture that is used for the CIM session. By default, the culture of the client is used when performing operations. However, the default culture can be overridden using the Culture parameter.

Parameters

-Culture

Specifies the user interface culture to use for the CIM session. Specify the value for this parameter using one of the following formats:

  • A culture name in <languagecode2>-<country/regioncode2> format such as "en-US".
  • A variable that contains a CultureInfo object.
  • A command that gets a CultureInfo object, such as Get-Culture

Parameter properties

Type:CultureInfo
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-EncodePortInServicePrincipalName

Indicates that the Kerberos connection is connecting to a service whose service principal name (SPN) includes the service port number. This type of connection is not common.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Encoding

Specifies the encoding used for the WsMan protocol. The acceptable values for this parameter are: Default, Utf8, or Utf16.

Parameter properties

Type:PacketEncoding
Default value:None
Accepted values:Default, Utf8, Utf16
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-HttpPrefix

Specifies the part of the HTTP URL after the computer name and port number. Changing this is not common. By default, the value of this parameter is /wsman.

Parameter properties

Type:Uri
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Impersonation

Creates a DCOM session to Windows Management Instrumentation (WMI) using impersonation.

Valid values for this parameter are:

  • Default: DCOM can choose the impersonation level using its normal security negotiation algorithm.
  • None: The client is anonymous to the server. The server process can impersonate the client, but the impersonation token does not contain any information and cannot be used.
  • Identify: Allows objects to query the credentials of the caller.
  • Impersonate: Allows objects to use the credentials of the caller.
  • Delegate: Allows objects to permit other objects to use the credentials of the caller.

If Impersonation is not specified, the New-CimSession cmdlet uses the value of Impersonate.

Parameter properties

Type:ImpersonationType
Default value:None
Accepted values:Default, None, Identify, Impersonate, Delegate
Supports wildcards:False
DontShow:False

Parameter sets

DcomParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-MaxEnvelopeSizeKB

Specifies the size limit of WsMan XML messages for either direction.

Parameter properties

Type:UInt32
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-NoEncryption

Specifies that data encryption is turned off.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-PacketIntegrity

Specifies that the DCOM session created to WMI uses the Component Object Model (COM) PacketIntegrity functionality. By default, all CIM sessions created using DCOM have the PacketIntegrity parameter set to True.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

DcomParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-PacketPrivacy

Creates a DCOM session to WMI using the COM PacketPrivacy. By default, all CIM sessions created using DCOM have the PacketPrivacy parameter set to true.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

DcomParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Protocol

Specifies the protocol to use. The acceptable values for this parameter are: Dcom, Default, or Wsman.

Parameter properties

Type:ProtocolType
Default value:None
Accepted values:Dcom, Default, Wsman
Supports wildcards:False
DontShow:False

Parameter sets

ProtocolTypeSet
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-ProxyAuthentication

Specifies the authentication method to use for proxy resolution. The acceptable values for this parameter are: Default, Digest, Negotiate, Basic, Kerberos, NtlmDomain, or CredSsp.

Parameter properties

Type:PasswordAuthenticationMechanism
Default value:None
Accepted values:Default, Digest, Negotiate, Basic, Kerberos, NtlmDomain, CredSsp
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-ProxyCertificateThumbprint

Specifies the (x.509) digital public key certificate of a user account for proxy authentication. Enter the certificate thumbprint of the certificate. Certificates are used in client certificate-based authentication. They can only be mapped to local user accounts and they do not work with domain accounts.

To get a certificate thumbprint, use the Get-Item or Get-ChildItem cmdlets in the PowerShell Cert: drive.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-ProxyCredential

Specifies the credentials to use for proxy authentication. Enter one of the following:

  • A variable that contains a PSCredential object.
  • A command that gets a PSCredential object, such as Get-Credential

If this option is not set, then you cannot specify any credentials.

Parameter properties

Type:PSCredential
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ProxyType

Specifies the host name resolution mechanism to use. The acceptable values for this parameter are: None, WinHttp, Auto, or InternetExplorer.

The default value of this parameter is InternetExplorer.

Parameter properties

Type:ProxyType
Default value:InternetExplorer
Accepted values:None, WinHttp, Auto, InternetExplorer
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-SkipCACheck

Indicates that when connecting over HTTPS, the client does not validate that the server certificate is signed by a trusted certification authority (CA).

Use this parameter only when the remote computer is trusted using another mechanism, such as when the remote computer is part of a network that is physically secure and isolated, or when the remote computer is listed as a trusted host in a WinRM configuration.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-SkipCNCheck

Indicates that the certificate common name (CN) of the server does not need to match the hostname of the server. Use this parameter for remote operations only with trusted computers that use the HTTPS protocol.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-SkipRevocationCheck

Indicates that the revocation check for server certificates is skipped. Use this parameter only for trusted computers.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-UICulture

Specifies the user interface culture to use for the CIM session. Specify the value for this parameter using one of the following formats:

  • A culture name in <languagecode2>-<country/regioncode2> format such as "en-US".
  • A variable that contains a CultureInfo object.
  • A command that gets a CultureInfo object, such as Get-Culture.

Parameter properties

Type:CultureInfo
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-UseSsl

Indicates that SSL should be used to establish a connection to the remote computer. By default, SSL is not used. WsMan encrypts all content that is transmitted over the network, even when using HTTP.

This parameter lets you specify the additional protection of HTTPS instead of HTTP. If SSL is not available on the port used for the connection and you specify this parameter, then the command fails.

It is recommended that you use this parameter only when the PacketPrivacy parameter is not specified.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

WSManParameterSet
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

None

You can't pipe objects to this cmdlet.

Outputs

CimSessionOptions

This cmdlet returns an object that contains CIM session options information.

Notes

PowerShell includes the following aliases for New-CimSessionOption:

  • Windows:
    • ncso

This cmdlet is only available on Windows platforms.