Create an object that contains advanced options for a PSSession.
Syntax New-PSSessionOption [-ApplicationArguments PSPrimitiveDictionary] [-CancelTimeOut int] [-Culture CultureInfo] [-IdleTimeOut int] [-MaximumReceivedDataSizePerCommand int] [-MaximumReceivedObjectSize int] [-MaximumRedirection int] [-NoCompression] [-NoEncryption] [-NoMachineProfile] [-OpenTimeOut int] [-OperationTimeOut int] [-ProxyAccessType ProxyAccessType] [-ProxyAuthentication AuthenticationMechanism] [-ProxyCredential PSCredential] [-SkipCACheck] [-SkipCNCheck] [-SkipRevocationCheck] [-UICulture CultureInfo] [-UseUTF16] [CommonParameters] Key -ApplicationArguments PSPrimitiveDictionary A hash table that is sent directly to the session configuration without interpretation. This hash table is available to the session configuration as a property of the PSSenderInfo class. -CancelTimeOut int How long PowerShell will wait for a cancel operation (CTRL + C) to complete before terminating. (int milliseconds) The default value is 60000 (one minute). A value of 0 (zero) means no timeout; the command continues indefinitely. -Culture CultureInfo The culture to use for the PSSession. Enter a culture name in languagecode2-country/regioncode2 format, such as "ja-jP", or a variable/command that gets a CultureInfo object, such as "get-culture". The default value is $null, and the culture that is set in the operating system when the PSSession is created is used in the PSSession. -IdleTimeOut int How long the PSSession will stay open if the remote computer does not receive any communication from the local computer, including the heartbeat signal. (int milliseconds) The default value is 240000 (4 minutes). The minimum value is 60000 (1 minute). When the interval expires, the PSSession closes. If both the local and remote computers specify an idle timeout value, the PSSession uses the shorter timeout value. The local computer can set an idle timeout value by using -IdleTimeOut or by setting an idle timeout in the $PSSessionOption preference variable. The remote computer can specify an idle timeout value in the WS-Management configuration (WSMAN:\localhost\shell\idletimeout). -MaximumReceivedDataSizePerCommand int The maximum number of bytes that the local computer can receive from the remote computer in a single command. Enter a value in bytes. By default, there is no data size limit. This option is designed to protect the resources on the client computer. -MaximumReceivedObjectSize int The maximum size of an object that the local computer can receive from the remote computer. Enter a value in bytes. By default, there is no data size limit. This option is designed to protect the resources on the client computer. -MaximumRedirection int How many times PowerShell will redirect a connection to an alternate Uniform Resource Identifier(URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection. This option is only used when -AllowRedirection is used in the command that creates the PSSession. -NoCompression Turn off packet compression in the PSSession. Compression uses more processor cycles, but it makes transmission faster. -NoEncryption Turn off data encryption. -NoMachineProfile Prevent loading the user's Windows user profile. As a result, the PSSession might be created faster, but user-specific registry settings, items such as environment variables, and certificates are not available in the PSSession. -OpenTimeOut int How long the client computer waits for the session connection to be established. (int milliseconds) When the interval expires, the command to establish the connection fails. The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the command continues indefinitely. -OperationTimeOut int The maximum time that any operation in the PSSession can run. (int milliseconds) When the interval expires, the operation fails. The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the operation continues indefinitely. -ProxyAccessType ProxyAccessType The mechanism is used to resolve the host name. Valid values are: IEConfig, WinHttpConfig, AutoDetect, NoProxyServer or None. -ProxyAuthentication AuthenticationMechanism The authentication method that is used for proxy resolution. Valid values are: Default | Basic | Credssp | Digest | Kerberos | Negotiate | NegotiateWithImplicitCredential -ProxyCredential PSCredential The credentials to use for proxy authentication. Enter a variable that contains a PSCredential object or a command that gets a PSCredential object, such as Get-Credential. If this option is not set, no credentials are specified. -SkipCACheck Specifies that when connecting over HTTPS, the client does not validate that the server certificate is signed by a trusted certificate authority (CA). Use this option only when the remote computer is trusted by using another mechanism, such as when the remote computer is part of a network that is physically secure and isolated, or the remote computer is listed as a trusted host in a WinRM configuration. -SkipCNCheck Specifies that the certificate common name (CN) of the server does not need to match the hostname of the server. This option is used only in remote operations that use the HTTPS protocol. Use this option only for trusted computers. -SkipRevocationCheck Do not validate the revocation status of the server certificate. -UICulture CultureInfo The UI culture to use for the PSSession. Enter a culture name in languagecode2-country/regioncode2 format, such as "ja-jP", or a variable/command that gets a CultureInfo object, such as "get-culture". The default value is $null, and the UI culture that is set in the operating system when the PSSession is created is used in the PSSession. -UseUTF16 Encode the request in UTF16 format rather than UTF8 format.
By default, the $PSSessionOption variable contains a PSSessionOption object with the default values for all options, as shown below.
MaximumConnectionRedirectionCount : 5 NoCompression : False NoMachineProfile : False ProxyAccessType : None ProxyAuthentication : Negotiate ProxyCredential : SkipCACheck : False SkipCNCheck : False SkipRevocationCheck : False OperationTimeout : 00:03:00 NoEncryption : False UseUTF16 : False IncludePortInSPN : False OutputBufferingMode : None Culture : UICulture : MaximumReceivedDataSizePerCommand : MaximumReceivedObjectSize : 209715200 ApplicationArguments : OpenTimeout : 00:03:00 CancelTimeout : 00:01:00 IdleTimeout : -00:00:00.0010000
Create a session option object with all of the default values:
PS C:> New-PSSessionOption
Create a session option object and edit some of its values:
PS C:> $a = new-pssessionoption PS C:> $a.UICulture = (get-UICulture) PS C:> $a.OpenTimeout = (new-timespan -minutes 4) PS C:> $a.MaximumConnectionRedirectionCount = 1
Use a session option object to configure a session:
PS C:> $pso = new-pssessionoption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB PS C:> new-pssession -computerName Server01 -SessionOption $pso
Start an interactive session with the Server64 computer, the New-PSSessionOption command is enclosed in parentheses to ensure it runs before Enter-PSSession:
PS C:> enter-pssession -computername Server64 -sessionOption (new-pssessionoption -noEncryption -noCompression)
Create a $PSSessionOption preference variable to establish default values for session options (to make this available in all sessions, add it to your PowerShell profile):
PS C:> $PSSessionOption = New-PSSessionOption -OpenTimeOut 120000
“Coping with the demands of everyday life would be exceedingly trying if one could arrive at solutions to problems only by actually performing possible options and suffering the consequences” ~ Albert Bandura
Related PowerShell Cmdlets:
Enable-PSSessionConfiguration - Enable PS session configuration.
Register-PSSessionConfiguration - Create and register a new PS session configuration.