This is the built-in help made by Microsoft for the command 'New-PSSessionOption', in PowerShell version 4 - as retrieved from
Windows version 'Microsoft Windows 8.1 Enterprise' PowerShell help files on 2016-06-23.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
Creates an object that contains advanced options for a PSSession.
New-PSSessionOption [-ApplicationArguments <PSPrimitiveDictionary>] [-CancelTimeout <Int32>] [-Culture <CultureInfo>] [-IdleTimeout <Int32>] [-IncludePortInSPN] [-Max
imumReceivedDataSizePerCommand <Int32>] [-MaximumReceivedObjectSize <Int32>] [-MaximumRedirection <Int32>] [-NoCompression] [-NoEncryption] [-NoMachineProfile] [-Open
Timeout <Int32>] [-OperationTimeout <Int32>] [-OutputBufferingMode <OutputBufferingMode>] [-ProxyAccessType <ProxyAccessType>] [-ProxyAuthentication <AuthenticationMe
chanism>] [-ProxyCredential <PSCredential>] [-SkipCACheck] [-SkipCNCheck] [-SkipRevocationCheck] [-UICulture <CultureInfo>] [-UseUTF16] [<CommonParameters>]
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 S
essionOption 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 all of the properties 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 session option object in the $PSSessionOption preference variable. The values of this variable establish new default values for the session option
s. They 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 session option object in a cmdlet that creates a session. For more information about the $PSSessionOption preference variable, see ab
out_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248).
When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the $PSSess
ionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configur
ation. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152).
<
Online Version: http://go.microsoft.com/fwlink/p/?linkid=289598
Enter-PSSession
Invoke-Command
New-PSSession
<
-------------------------- EXAMPLE 1 --------------------------
PS C:\>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
This command creates a session option object with all of the default values.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
PS C:\>New-PSSession -ComputerName Server01 -SessionOption $pso
This example shows how to use a session option object to configure a session.
The first command creates a new session option 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 session option object in the value of the $
pso variable as the value of the SessionOption parameter of the command.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)
This command uses the Enter-PSSession cmdlet to start an interactive session with the Server01 computer. The value of the SessionOption parameter is a New-PSSessionOp
tion command with the NoEncryption and NoCompression switch parameters.
The New-PSSessionOption command is enclosed in parentheses to make sure that it runs before the Enter-PSSession command.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>$a = 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
PS C:\>$a.UICulture = (Get-UICulture)
PS C:\>$a.OpenTimeout = (New-Timespan -Minutes 4)
PS C:\>$a.MaximumConnectionRedirectionCount = 1
PS C:\>$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
This example demonstrates that you can edit the session option object. All properties have read/write values.
Use this method to create a standard session object for your enterprise, and then create customized versions of it for particular uses.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000
This command creates a $PSSessionOption preference variable.
When the $PSSessionOption preference variable exists in the session, it establishes default values for options in the sessions that are created by using the New-PSSes
sion, Enter-PSSession, and Invoke-Command cmdlets.
To make the $PSSessionOption variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile.
For more information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). For more informat
ion about profiles, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729).
-------------------------- EXAMPLE 6 --------------------------
PS C:\>$skipCN = New-PSSessionOption -SkipCNCheck
PS C:\>New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN
This example shows how to use a SessionOption object to fulfill the requirements for a remote session configuration.
The first command uses the New-PSSessionOption cmdlet to create a session option object with 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 pa
rameter.
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 used for Secur
e Sockets Layer (SSL). As a result, the SkipCNCheck option is required.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>$team = @{Team="IT"; Use="Testing"}
PS C:\>$TeamOption = New-PSSessionOption -ApplicationArguments $team
PS C:\>$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
PS C:\>Invoke-Command -Session $s {$PSSenderInfo.SpplicationArguments}
Name Value
---- -----
Team IT
Use Testing
PSVersionTable {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}
PS C:\>Invoke-Command -Session $s {if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {.\logFiles.ps1} else {"Just testing."}}
Just testing.
This example shows how to use the ApplicationArguments parameter of the New-PSSessionOption cmdlet to make additional data available to the remote session.
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, s
ee about_Hash_Tables (http://go.microsoft.com/fwlink/?LinkID=135175).)
The second command uses the ApplicationArguments parameter of the New-PSSessionOption cmdlet to create a session option object that contains the data in the $team var
iable. The command saves the session option object in the $teamOption variable.
When New-PSSessionOption creates the session option object, it automatically converts the hash table in the value of the ApplicationArguments parameter to a primitive
dictionary so the data can be reliably transmitted to the remote session.
The third command uses the New-PSSession cmdlet to start a session on the Server01 computer. It uses the SessionOption parameter to include the options in the $teamOp
tion variable.
The fourth command demonstrates that the data in the $team variable is available to commands in the remote session. The data appears in the ApplicationArguments prope
rty of the $PSSenderInfo automatic variable.
The fifth command shows how the data might be used. The command uses the Invoke-Command cmdlet to run a script only when the value of the Use property is not "Testing
". When the value of Use is "Testing", the command returns "Just testing."