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.

   -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

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.


 
Copyright © 1999-2024 SS64.com
Some rights reserved