New-PSSessionOption

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.

-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.

CommonParameters:
-Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer -OutVariable.

Examples

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.