New-PSSessionOption PowerShell Command

New-PSSessionOption | Taking on PowerShell one cmdlet at a time | Weekly Blog

Share this post:

This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers New-PSSessionOption.

When to use New-PSSessionOption?

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-PSSessionEnter-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 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 session option object in a cmdlet that creates a session.

NOTE: 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 $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.

What version of PowerShell am I using?

Get the PowerShell Version from your machine:

$PSVersionTable

This command shows you the PowerShell version information on your machine.

How to use New-PSSessionOption?

Create a default session option:

New-PSSessionOption

This command creates a session option object that has all of the default values.

Configure a session by using a session option object:

$pso = New-PSSessionOption -Culture “en-en” -MaximumReceivedObjectSize 10MB

New-PSSession -ComputerName ITPTV01 -SessionOption $pso

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

Start an interactive session:

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

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

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

Modify a session option object:

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

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

Create a preference variable:

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

When the $PSSessionOption preference variable occurs in the session, it establishes default values for options in the sessions that are created by using the New-PSSessionEnter-PSSession, and Invoke-Command cmdlets.

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

Learn last week’s command: New-PSSession.

Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.