New-PSSession Option

Syntax

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

Description

The New-PSSessionOption cmdlet creates an object that contains advanced options for a user-managed session ( PSSession ). You can use the object as the value of the SessionOption parameter of cmdlets that create a PSSession , such as New-PSSession , Enter-PSSession , and Invoke-Command .

Without parameters, New-PSSessionOption generates an object that contains the default values for all of the options. Because every property can be edited, you can use the resulting object as a template and create standard option objects for your enterprise.

You can also save a SessionOption object in the $PSSessionOption preference variable. The values of this variable establish new default values for the session options. They are effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a SessionOption object in a cmdlet that creates a session. For more information about the $PSSessionOption preference variable, see about_Preference_Variables .

When you use a SessionOption object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For more information about session configurations, see about_Session_Configurations .

Examples

Example 1: Create a default session option

This command creates a SessionOption object with the default values.

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Example 2: Configure a session by using a session option object

This example shows how to use a SessionOption object to configure a session.

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

The first command creates a new SessionOption object and saves it in the value of the $pso variable. The second command uses the New-PSSession cmdlet to create a session on the Server01 remote computer. The command uses the SessionOption object in the value of the $pso variable as the value of the SessionOption parameter of the command.

Example 3: Start an interactive session

This command uses the Enter-PSSession cmdlet to start an interactive session with the Server01 computer.

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

The value of the SessionOption parameter is a New-PSSessionOption command that has the NoEncryption and NoCompression parameters.

The New-PSSessionOption command is enclosed in parentheses to make sure that it runs before the Enter-PSSession command.

Example 4: Modify a session option object

This example demonstrates that you can modify the SessionOption object. All properties have read/write values.

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Use this method to create a standard session object for your enterprise, and then create customized versions of it for particular uses.

Example 5: Create a preference variable

This command creates a $PSSessionOption preference variable.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

When the $PSSessionOption preference variable is set in the session, it establishes default values for options in the sessions that are created with the New-PSSession , Enter-PSSession , and Invoke-Command cmdlets.

To make the $PSSessionOption variable available in all sessions, add it to your PowerShell session and to your PowerShell profile.

For more information about the $PSSessionOption preference variable, see about_Preference_Variables . For more information about profiles, see about_Profiles .

Example 6: Fulfill the requirements for a remote session configuration

This example shows how to use a SessionOption object to fulfill the requirements for a remote session configuration.

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

The first command uses the New-PSSessionOption cmdlet to create a SessionOption object that has the SkipCNCheck property. The command saves the resulting session object in the $skipCN variable.

The second command uses the New-PSSession cmdlet to create a new session on a remote computer. The $skipCN check variable is used in the value of the SessionOption parameter.

Because the computer is identified by its IP address, the value of the ComputerName parameter does not match any of the common names in the certificate that is used for Secure Sockets Layer (SSL). As a result, the SkipCNCheck option is required.

Example 7: Make arguments available to a remote session

This example shows how to use the ApplicationArguments parameter of the New-PSSessionOption cmdlet to make additional data available to the remote session.

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

The first command creates a hash table with two keys, Team and Use . The command saves the hash table in the $team variable. For more information about hash tables, see about_Hash_Tables .

Next, the New-PSSessionOption cmdlet, using the ApplicationArguments parameter, creates a SessionOption object saved in the $team variable. When New-PSSessionOption creates the session option object, it automatically converts the hash table in the value of the ApplicationArguments parameter to a PrimitiveDictionary so the data can be reliably transmitted to the remote session.

The New-PSSession cmdlet starts a session on the Server01 computer. It uses the SessionOption parameter to include the options in the $teamOption variable.

The Invoke-Command cmdlet demonstrates that the data in the $team variable is available to commands in the remote session. The data appears in the ApplicationArguments property of the $PSSenderInfo automatic variable.

The final Invoke-Command shows how the data might be used.

Parameters

-ApplicationArguments

-CancelTimeout

-Culture

-IdleTimeout

-IncludePortInSPN

-MaxConnectionRetryCount

-MaximumReceivedDataSizePerCommand

-MaximumReceivedObjectSize

-MaximumRedirection

-NoCompression

-NoEncryption

-NoMachineProfile

-OpenTimeout

-OperationTimeout

-OutputBufferingMode

-ProxyAccessType

-ProxyAuthentication

-ProxyCredential

-SkipCACheck

-SkipCNCheck

-SkipRevocationCheck

-UICulture

-UseUTF16

Inputs

None

You can't pipe objects to this cmdlet.

Outputs

PSSessionOption

Notes

If the SessionOption parameter is not used in a command to create a PSSession , the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see about_Preference_Variables .

The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties.

Related Links

• Enter-PSSession
• Invoke-Command
• New-PSSession