CmdID / PowerShell / Cmdlets / Set
Set-PSSessionConfiguration
Changes the properties of a registered session configuration. PowerShell reference
From the PowerShell reference 23 parameters
What it does
Changes the properties of a registered session configuration. 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 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. 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.
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>]Change the thread apartment state
PS C:> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STAIdentifyCreate and change a session configuration
Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $nullIdentifyDisplay results
Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20IdentifyDisplay results in different ways
Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"IdentifyIts page in the reference: Set-PSSessionConfiguration.
Parameters
Show its 23 parameters
-AccessModeEnables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. The acceptable values for this parameter are:
- Disabled. Disables the session configuration. It cannot be used for remote or local access to
the computer. This value sets the Enabled property of the session configuration
(WSMan:<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) to False.
- Local. Adds a Network_Deny_All entry to security descriptor of the session configuration.
Users of the local computer can use the session configuration to create a local loopback session
on the same computer, but remote users are denied access.
- Remote. Removes Deny_All and Network_Deny_All entries from the security descriptors of
the session configuration. Users of local and remote computers can use the session configuration
to create sessions and run commands on this computer.
The default value is Remote.
Other cmdlets can override the value of this parameter later. For example, the Enable-PSRemoting
cmdlet enables all session configurations on the computer and permits remote access to them, and the …-ApplicationBaseSpecifies the path of the assembly file (*.dll) that is specified in the value of the AssemblyName parameter.-AssemblyNameSpecifies the assembly name. This cmdlet creates a session configuration based on a class that is defined in an assembly.
Enter the filename or full path of an assembly .dll file that defines a session configuration. If you enter only the file name, you can enter the path in the value of the ApplicationBase parameter.-ConfigurationTypeNameSpecifies the type of the session configuration that is defined in the assembly in the AssemblyName parameter. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class.
This parameter is required when you specify an assembly name.-ForceSuppresses all user prompts, and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective.
To prevent a restart and suppress the restart prompt, use the NoServiceRestart parameter.-MaximumReceivedDataSizePerCommandMBSpecifies the limit on the amount of data that can be sent to this computer in any single remote command. Enter the data size in megabytes (MB). The default is 50.
If a data size limit is defined in the configuration type that is specified in the ConfigurationTypeName parameter, the limit in the configuration type is used. The value of this parameter is ignored.-MaximumReceivedObjectSizeMBSpecifies the limits on the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes. The default is 10.
If an object size limit is defined in the configuration type that is specified in the ConfigurationTypeName parameter, the limit in the configuration type is used. The value of this parameter is ignored.-ModulesToImportSpecifies the modules and snap-ins that are automatically imported into sessions that use the session configuration. Enter the module and snap-in names.
By default, only the Microsoft.PowerShell.Core module is imported into sessions, but unless the
cmdlets are excluded, you can use the Import-Module and Add-PSSnapin cmdlets to add modules and
snap-ins to the session.
The modules specified in this parameter value are imported in additions to modules specified in the session configuration file (New-PSSessionConfigurationFile). However, settings in the session configuration file can hide the commands exported by modules or prevent users from using them.
The modules specified in this parameter value replace the list of modules specified with the ModulesToImport parameter of the Register-PSSessionConfiguration cmdlet.
This parameter was introduced in PowerShell 3.0.-NameSpecifies the name of the session configuration that you want to change.
You cannot use this parameter to change the name of the session configuration.-NoServiceRestartDoes not restart the WinRM service, and suppresses the prompt to restart the service.
By default, when you run Set-PSSessionConfiguration, you are prompted to restart the WinRM service to make the new session configuration effective. Until the WinRM service is restarted, the new session configuration is not effective.
To restart the WinRM service without prompting, use the Force parameter. To restart the WinRM service manually, use the Restart-Service cmdlet.-PathSpecifies the path of a session configuration file (.pssc), such as one created by the
New-PSSessionConfigurationFile cmdlet. If you omit the path, the default is the current directory.
For information about how to modify a session configuration file, see the help topic for the
New-PSSessionConfigurationFile cmdlet.
This parameter was introduced in PowerShell 3.0.-PSVersionSpecifies the version of PowerShell in sessions that use this session configuration.
The value of this parameter takes precedence over the value of the PowerShellVersion key in the session configuration file.
This parameter was introduced in PowerShell 3.0.-RunAsCredentialSpecifies credentials for commands in the session. By default, commands run with the permissions of the current user.
This parameter was introduced in PowerShell 3.0.-SecurityDescriptorSddlSpecifies a different Security Descriptor Definition Language (SDDL) string for the configuration.
This string determines the permissions that are required to use the new session configuration. To use a session configuration in a session, users must have at least Execute(Invoke) permission for the configuration.
To use the default security descriptor for the configuration, enter an empty string ("") or a value of $null. The default is the root SDDL in the WSMan: drive.
If the security descriptor is complex, consider using the ShowSecurityDescriptorUI parameter instead of this one. You cannot use both parameters in the same command.-SessionTypeOptionSpecifies type-specific options for the session configuration. Enter a session type options object, such as the PSWorkflowExecutionOption object that the New-PSWorkflowExecutionOption cmdlet returns.
The options of sessions that use the session configuration are determined by the values of session options and the session configuration options. Unless specified, options set in the session, such as with the New-PSSessionOption cmdlet, take precedence over options set in the session configuration. However, session option values cannot exceed maximum values set in the session configuration.
This parameter was introduced in PowerShell 3.0.-ShowSecurityDescriptorUIWhen this parameter is used the cmdlet opens a property sheet that helps you create a new SDDL for the session configuration. The property sheet appears after you run the Set-PSSessionConfiguration command and then restart the WinRM service.
When you set permissions to the configuration, remember that users must have at least Execute(Invoke) permission to use the session configuration in a session.
You cannot use the SecurityDescriptorSDDL parameter and this parameter in the same command.-StartupScriptSpecifies the startup script for the configuration. Enter the fully qualified path of a PowerShell script. The specified script runs in the new session that uses the session configuration.
To delete a startup script from a session configuration, enter an empty string ("") or a value of
$null.
You can use a startup script to further configure the user session. If the script generates an error, even a non-terminating error, the session is not created and the New-PSSession command fails.-ThreadApartmentStateSpecifies the apartment state of the threading module to be used. Acceptable values are:
- Unknown
- MTA
- STA-ThreadOptionsSpecifies the thread options setting in the configuration. This setting defines how threads are created and used when a command is executed in the session. The acceptable values for this parameter are:
- Default
- ReuseThread
- UseCurrentThread
- UseNewThread
The default value is UseCurrentThread.
For more information, see PSThreadOptions Enumeration.-TransportOptionSpecifies the transport options for the session configuration. Enter a transport options object, such as the WSManConfigurationOption object that the New-PSTransportOption cmdlet returns.
The options of sessions that use the session configuration are determined by the values of session options and the session configuration options. Unless specified, options set in the session, such as with the New-PSSessionOption cmdlet, take precedence over options set in the session configuration. However, session option values cannot exceed maximum values set in the session configuration.
This parameter was introduced in PowerShell 3.0.-UseSharedProcessUse only one process to host all sessions that are started by the same user and use the same session configuration. By default, each session is hosted in its own process.
This parameter was introduced in PowerShell 3.0.-ConfirmPrompts you for confirmation before running the cmdlet.-WhatIfShows what would happen if the cmdlet runs. The cmdlet is not run.