Register-PSSessionConfiguration

Creates and registers a new session configuration. PowerShell reference

From the PowerShell reference 25 parameters

What it does

from the PowerShell reference, CC BY 4.0

Creates and registers a new session configuration. The Register-PSSessionConfiguration cmdlet creates and registers a new session configuration on the local computer. This is an advanced cmdlet that you can use to create custom sessions for remote users. Every PowerShell session (PSSession) uses a session configuration, also known as an endpoint. When users create a session that connects to the computer, they can select a session configuration or use the default session configuration that's registered when you enable PowerShell remoting. Users can also set the $PSSessionConfigurationName preference variable, which specifies a default configuration for remote sessions created in the current session. The session configuration defines the environment for the remote session. The configuration can determine which commands and language elements are available in the session, and it can include settings that protect the computer, such as those that limit the amount of data that the session can receive remotely in a single object or command. The security descriptor of the session configuration determines which users have permission to use the session configuration. You can define the elements of configuration by using an assembly that implements a new configuration class and by using a script that runs in the session. Beginning in PowerShell 3.0, you can also use a session configuration file to define the session configuration. For information about session configurations, see about_Session_Configurations. For information about session configuration files, see about_Session_Configuration_Files.

Register-PSSessionConfiguration [-ProcessorArchitecture <String>] [-SessionType <PSSessionType>] [-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>]

Register-PSSessionConfiguration [-ProcessorArchitecture <String>] [-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>]

Register-PSSessionConfiguration [-ProcessorArchitecture <String>] [-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>]

$sessionConfiguration = @{
Name='NewShell'
ApplicationBase='C:\MyShells\'
AssemblyName='MyShell.dll'
ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

Identify

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1Identify

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FASA;GWGX;;;WD)"
$sessionParams = @{
Name="AdminShell"
SecurityDescriptorSDDL=$sddl
MaximumReceivedObjectSizeMB=20
StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams

Identify

Return a configuration container element

$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin

Identify

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1Identify

Its page in the reference: Register-PSSessionConfiguration.

Parameters

25 in the PowerShell reference

Show its 25 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 can't be used for remote or local access to the computer. - Local. Allows users of the local computer to use the session configuration to create a local loopback session on the same computer, but denies access to remote users. - Remote. Allows local and remote users to 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 allows for remote access to all session configurations, the Enable-PSSessionConfiguration cmdlet enables session configurations, and the Disable-PSRemoting cmdlet prevents remote access to all session configurations. This parameter was introduced in PowerShell 3.0.

-ApplicationBaseSpecifies the path of the assembly file (*.dll) that's specified in the value of the AssemblyName parameter. Use this parameter when the value of the AssemblyName parameter doesn't include a path. The default is the current directory.

-AssemblyNameSpecifies the name of an assembly file (\*.dll) in which the configuration type is defined. You can specify the path of the .dll in this parameter or in the value of the ApplicationBase parameter. This parameter is required when you specify the ConfigurationTypeName parameter.

-ConfigurationTypeNameSpecifies the fully qualified name of the Microsoft .NET Framework type that's used for this configuration. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class. To specify the assembly file (*.dll) that implements the configuration type, specify the AssemblyName and ApplicationBase parameters. Creating a type lets you control more aspects of the session configuration, such as exposing or hiding certain parameters of cmdlets, or setting data size and object size limits that users can't override. If you omit this parameter, the DefaultRemotePowerShellConfiguration class is used for the session configuration.

-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, specify the NoServiceRestart parameter.

-MaximumReceivedDataSizePerCommandMBSpecifies a limit for 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 MB. If a data size limit is defined in the configuration type that's specified in the ConfigurationTypeName parameter, the limit in the configuration type is used and the value of this parameter is ignored.

-MaximumReceivedObjectSizeMBSpecifies a limit for 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 MB. If an object size limit is defined in the configuration type that's specified in the ConfigurationTypeName parameter, the limit in the configuration type is used and the value of this parameter is ignored.

-ModulesToImportSpecifies the modules that are automatically imported into sessions that use the session configuration. By default, only Microsoft.PowerShell.Core is imported into sessions. Unless the cmdlets are excluded, you can use Import-Module to add modules to the session. The modules specified in this parameter value are imported in additions to modules that are specified by the SessionType parameter and those listed in the ModulesToImport key 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. This parameter was introduced in PowerShell 3.0.

-NameSpecifies a name for the session configuration. This parameter is required.

-NoServiceRestartThe intent of this parameter is to prevent the restart the WinRM service. This functionality isn't implemented. This functionality was implemented in PowerShell 7.5.0-preview.4, but there's no plan to back port this change to Windows PowerShell 5.1.

-PathSpecifies the path and filename of a session configuration file (.pssc), such as one created by New-PSSessionConfigurationFile. If you omit the path, the default is the current directory. This parameter was introduced in PowerShell 3.0.

-ProcessorArchitectureDetermines whether a 32-bit or 64-bit version of the PowerShell process is started in sessions that use this session configuration. The acceptable values for this parameter are: x86 (32-bit) and AMD64 (64-bit). The default value is determined by the processor architecture of the computer that hosts the session configuration. You can use this parameter to create a 32-bit session on a 64-bit computer. Attempts to create a 64-bit process on a 32-bit computer fail.

-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 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. If the security descriptor is complex, consider using the ShowSecurityDescriptorUI parameter instead of this parameter. You can't use both parameters in the same command. If you omit this parameter, the root SDDL for the WinRM service is used for this configuration. To view or change the root SDDL, use the WSMan provider. For example Get-Item WSMan:\localhost\service\rootSDDL. For more information about the WSMan provider, type Get-Help WSMan.

-SessionTypeSpecifies the type of session that is created by using the session configuration. The acceptable values for this parameter are: - Empty. No modules are added to session by default. Use the parameters of this cmdlet to add modules, functions, scripts, and other features to the session. - Default. Adds Microsoft.PowerShell.Core to the session. This module includes the Import-Module cmdlet that users can use to import other modules unless you explicitly prohibit the cmdlet. - RestrictedRemoteServer. Includes only the following cmdlets: Exit-PSSession, Get-Command, Get-FormatData, Get-Help, Measure-Object, Out-Default, and Select-Object. Use a script or assembly, or the keys in the session configuration file, to add modules, functions, scripts, and other features to the session. The default value is Default. The value of this parameter takes precedence over the value of the SessionType key in the session configuration file. This parameter was introduced in PowerShell 3.0.

-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 by using the New-PSSessionOption cmdlet, take precedence over options set in the session configuration. However, session option values can't exceed maximum values set in the session configuration. This parameter was introduced in PowerShell 3.0.

-ShowSecurityDescriptorUIIndicates that this cmdlet displays a property sheet that helps you create the SDDL for the session configuration. The property sheet appears after you enter the Register-PSSessionConfiguration command and then restart the WinRM service. When setting the permissions for the configuration, remember that users must have at least Execute (Invoke) permission to use the session configuration in a session. You can't use the SecurityDescriptorSDDL parameter and this parameter in the same command.

-StartupScriptSpecifies the fully qualified path of a PowerShell script. The specified script runs in the new session that uses the session configuration. You can use the script to additionally configure the session. If the script generates an error, even a non-terminating error, the session isn't 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 how threads are created and used when a command runs 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 option. 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 isn't run.

Register-PSSessionConfiguration

What it does

Parameters

See also