Set-PSSession Configuration

Syntax

Set-PSSessionConfiguration
   [-Name] <String>
   [-ApplicationBase <String>]
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Set-PSSessionConfiguration
   [-Name] <String>
   [-AssemblyName] <String>
   [-ApplicationBase <String>]
   [-ConfigurationTypeName] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Set-PSSessionConfiguration
   [-Name] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-TransportOption <PSTransportOption>]
   -Path <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The Set-PSSessionConfiguration cmdlet changes the properties of the session configurations on the local computer.

Use the Name parameter to identify the session configuration that you want to change. Use the other parameters to specify new values for the properties of the session configuration. To delete a property value from the configuration, and use the default value, enter an empty string ("") or a value of $Null for the corresponding parameter.

Starting in Windows PowerShell 3.0, you can use a session configuration file to define a session configuration. This feature provides a simple and discoverable method for setting and changing the properties of sessions that use the session configuration. To specify a session configuration file, use the Path parameter of Set-PSSessionConfiguration . For information about session configuration files, see about_Session_Configuration_Files ( http://go.microsoft.com/fwlink/?LinkID=236023 ). For information about how to create and modify a session configuration file, see the New-PSSessionConfigurationFile cmdlet.

Session configurations define the environment of remote sessions ( PSSessions ) that connect to the local computer. Every PSSession uses a session configuration. The session configuration determines the features of the PSSession , such as the modules that are available in the session, the cmdlets that are permitted to run, the language mode, quotas, and timeouts. The security descriptor of the session configuration determines who can use the session configuration to connect to the local computer. For more information about session configurations, see about_Session_Configurations.

To see the properties of a session configuration, use the Get-PSSessionConfiguration cmdlet or the WSMan Provider. For more information about the WSMan Provider, type Get-Help WSMan .

Examples

Example 1: Change the thread apartment state

PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA

This command changes the thread apartment state in the MaintenanceShell configuration to STA. The change is effective when you restart the WinRM service.

Example 2: Create and change a session configuration

The first command uses the **Register-PSSessionConfiguration** cmdlet to create the AdminShell configuration.

PS C:\> Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"



The second command uses the **Set-PSSessionConfiguration** cmdlet to add the AdminConfig.ps1 script to the configuration. The change is effective when you restart **WinRM**.

PS C:\> Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"



The third command removes the AdminConfig.ps1 script from the configuration. It uses the **Set-PSSessionConfiguration** cmdlet with a value of $Null for the *StartupScript* parameter.

PS C:\> Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

Example 3: Display results

PS C:\> Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue

---------                       ----------

psmaximumreceivedobjectsizemb   20

"Restart WinRM service"

WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?

[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

The Set-PSSessionConfiguration command in this example increases the value of the MaximumReceivedObjectSizeMB property to 20.

The Set-PSSessionConfiguration command returns a Microsoft.WSMan.Management.WSManConfigLeafElement object that shows the parameter name and new value.

This command also prompts you to restart the WinRM service. The change is not effective until the WinRM service is restarted.

Example 4: Display results in different ways

The first command uses the **Set-PSSessionConfiguration** cmdlet to change the startup script in the MaintenanceShell session configuration to Maintenance.ps1. The output of this command shows the change and prompts you to restart the **WinRM** service. The response is "y" (yes).

PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters



ParamName            ParamValue

---------            ----------

startupscript        c:\ps-test\Mainte...



"Restart WinRM service"

WinRM service need to be restarted to make the changes effective. Do you want to run

the command "restart-service winrm"?

[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y





The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session configuration. The command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet, which displays all of the properties of the session configuration object in a list.

PS C:\> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration

Name             : MaintenanceShell

Filename         : %windir%\system32\pwrshplugin.dll

SDKVersion       : 1

XmlRenderingType : text

lang             : en-US

PSVersion        : 2.0

startupscript    : c:\ps-test\Maintenance.ps1

ResourceUri      : http://schemas.microsoft.com/powershell/MaintenanceShell

SupportsOptions  : true

ExactMatch       : true

Capability       : {Shell}

Permission       :



The third command uses the WSMan provider to view the initialization parameters for the MaintenanceShell configuration. The command uses the Get-ChildItem cmdlet, also known as dir, to get the child items in the **InitializationParameters** node for the MaintenanceShell plug-in.For more information about the WSMan provider, type [CODE_Snippit]Get-Help wsman[CODE_Snippit].

PS C:\> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName     ParamValue

---------     ----------

PSVersion     2.0

startupscript c:\ps-test\Maintenance.ps1

Required Parameters

Optional Parameters

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

Microsoft.WSMan.Management.WSManConfigLeafElement

Notes

• To run this cmdlet, start Windows PowerShell by using the Run as administrator option.
• The Set-PSSessionConfiguration cmdlet does not change the configuration name and the WSMan provider does not support the Rename-Item cmdlet. To change the name of a session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration.
• You can use the Set-PSSessionConfiguration cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it.
• 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.
• You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as OutputBufferingMode . Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0.

Related Links

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• New-PSSessionOption
• New-PSTransportOption
• Register-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration