Export (0) Print
Expand All

Register-PSSessionConfiguration

Published: February 29, 2012

Updated: August 15, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

Register-PSSessionConfiguration

Creates and registers a new session configuration.

Syntax

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

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

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




Detailed Description

The Register-PSSessionConfiguration cmdlet creates and registers a new session configuration on the local computer. This is an advanced cmdlet that is designed to be used by system administrators to create custom sessions for remote users.

Every Windows 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 is registered when you enable Windows 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 (ACL) 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 Windows 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 (http://go.microsoft.com/fwlink/?LinkID=145152). For information about session configuration files, see about_Session_Configuration_Files (http://go.microsoft.com/fwlink/?LinkID=236023).

Parameters

-AccessMode<PSSessionConfigurationAccessMode>

Enables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. Remote is the default.

Valid values are:

-- Disabled: Disables the session configuration. It cannot 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 value of this parameter can be overridden at a later time by the actions of other cmdlets. For example, the Enable-PSRemoting cmdlet allows 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 is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

Remote

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ApplicationBase<String>

Specifies the path to the assembly file (*.dll) that is specified in the value of the AssemblyName parameter. Use this parameter when the value of the AssemblyName parameter does not include a path. The default is the current directory.


Aliases

none

Required?

false

Position?

named

Default Value

Current directory

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-AssemblyName<String>

Specifies the name of an assembly file (*.dll) in which the configuration type is defined. You can specify the path to the .dll in this parameter or in the value of the ApplicationBase parameter.

This parameter is required when the ConfigurationTypeName parameter is specified.


Aliases

none

Required?

true

Position?

2

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ConfigurationTypeName<String>

Specifies the fully qualified name of the Microsoft .NET Framework type that is 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, use the AssemblyName and ApplicationBase parameters.

Creating a type allows you to 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 cannot override.

If you omit this parameter, the DefaultRemotePowerShellConfiguration class is used for the session configuration.


Aliases

none

Required?

true

Position?

3

Default Value

System.Management.Automation.Remoting.PSSessionConfiguration

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Force

Suppresses all users 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.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-MaximumReceivedDataSizePerCommandMB<Double>

Limits 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 is specified in the ConfigurationTypeName parameter, the limit in the configuration type is used and the value of this parameter is ignored.


Aliases

none

Required?

false

Position?

named

Default Value

50

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-MaximumReceivedObjectSizeMB<Double>

Limits the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes (MB). The default is 10 MB.

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 and the value of this parameter is ignored.


Aliases

none

Required?

false

Position?

named

Default Value

10

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Name<String>

Specifies a name for the session configuration. This parameter is required.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-NoServiceRestart

Does not restart the WinRM service, and suppresses the prompt to restart the service.

By default, when you enter a Register-PSSessionConfiguration command, 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.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Path<String>

Specifies the path and file name 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.

This parameter is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

true

Position?

named

Default Value

Current directory

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ProcessorArchitecture<String>

Determines whether a 32-bit or 64-bit version of the Windows PowerShell process is started in sessions that use this session configuration. Valid values 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.


Aliases

PA

Required?

false

Position?

named

Default Value

The processor architecture of the host computer.

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-PSVersion<Version>

Specifies the version of Windows 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 is introduced in Windows PowerShell 3.0.


Aliases

PowerShellVersion

Required?

false

Position?

named

Default Value

3.0

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-RunAsCredential<PSCredential>

Runs commands in the session with the permissions of the specified user. By default, commands run with the permissions of the current user.

This parameter is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

Current user

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-SecurityDescriptorSddl<String>

Specifies 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 cannot 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".


Aliases

none

Required?

false

Position?

named

Default Value

The value of the root SDDL

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-SessionType<PSSessionType>

Specifies the type of session that is created by using the session configuration. The default value is Default. Valid values are:

-- Empty: No modules or snap-ins 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 the Microsoft.PowerShell.Core snap-in to the session. This module includes the Import-Module and Add-PSSnapin cmdlets that users can use to import other modules and snap-ins unless you explicitly prohibit the use of the cmdlets.

-- 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 value of this parameter takes precedence over the value of the SessionType key in the session configuration file.

This parameter is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

Default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-SessionTypeOption<PSSessionTypeOption>

Sets 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 cannot exceed maximum values set in the session configuration.

This parameter is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ShowSecurityDescriptorUI

Displays a property sheet that helps you to 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 cannot use the SecurityDescriptorSDDL parameter and this parameter in the same command.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-StartupScript<String>

Specifies the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration.

You can use the script to further configure the session. If the script generates an error (even a non-terminating error), the session is not created and the user's New-PSSession command fails.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ThreadApartmentState<ApartmentState>

Determines the apartment state of the threads in the session. Valid values are STA, MTA, and Unknown. Unknown is the default.


Aliases

none

Required?

false

Position?

named

Default Value

Unknown

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ThreadOptions<PSThreadOptions>

Defines how threads are created and used when a command is executed in the session. Valid values are Default, ReuseThread, UseCurrentThread, and UseNewThread. UseCurrentThread is the default.

For more information, see "PSThreadOptions Enumeration" in MSDN.


Aliases

none

Required?

false

Position?

named

Default Value

UseCurrentThread

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-TransportOption<PSTransportOption>

This parameter is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-UseSharedProcess

Use 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 is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ModulesToImport<String[]>

Specifies the modules and snap-ins that are automatically imported into sessions that use the session configuration.

By default, only the Microsoft.PowerShell.Core snap-in is imported into sessions, but unless the cmdlets are excluded, users 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 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 is introduced in Windows PowerShell 3.0.


Aliases

none

Required?

false

Position?

named

Default Value

Microsoft.PowerShell.Core

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Confirm

Prompts you for confirmation before running the cmdlet.


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • None

    You cannot pipe input to this cmdlet.


Outputs

The output type is the type of the objects that the cmdlet emits.

  • Microsoft.WSMan.Management.WSManConfigContainerElement

Notes

  • To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, start Windows PowerShell with the "Run as administrator" option.

    This cmdlet generates XML that represents a Web Services for Management (WS-Management) plug-in configuration and sends the XML to WS-Management, which registers the plug-in on the local computer ("new-item wsman:\localhost\plugin").

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

Examples

-------------------------- EXAMPLE 1 --------------------------

This command registers the NewShell session configuration. It uses the AssemblyName and ApplicationBase parameters to specify the location of the MyShell.dll file, which specifies the cmdlets and providers in the session configuration. It also uses the ConfigurationTypeName parameter to specify a new class that further configures the session.

To use this configuration, type "new-pssession -configurationname newshell".


PS C:\> Register-PSSessionConfiguration -Name NewShell -ApplicationBase c:\MyShells\ -AssemblyName MyShell.dll -ConfigurationTypeName MyClass

-------------------------- EXAMPLE 2 --------------------------

This command registers the MaintenanceShell configuration on the local computer. The command uses the StartupScript parameter to specify the Maintenance.ps1 script.

When a user uses a New-PSSession command and selects the MaintenanceShell configuration, the Maintenance.ps1 script runs in the new session. The script can configure the session, including importing modules, adding Windows PowerShell snap-ins, and setting the execution policy for the session. If the script generates any errors, including non-terminating errors, the New-PSSession command fails.


PS C:\> Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

-------------------------- EXAMPLE 3 --------------------------

This example registers the AdminShell session configuration.

The first command saves a custom SDDL in the $sddl variable.

The second command registers the new shell. The command uses the SecurityDescritorSDDL parameter to specify the SDDL in the value of the $sddl variable and the MaximumReceivedObjectSizeMB parameter to increase the object size limit. It also uses the StartupScript parameter to specify a script that configures the session.

As an alternative to using the SecurityDescriptorSDDL parameter, you can use the ShowSecurityDescriptorUI parameter, which displays a property sheet that you can use to set permissions for the session configuration. When you click "OK" in the property sheet, the tool generates an SDDL for the session configuration.


PS C:\> $sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"
PS C:\>Register-PSSessionConfiguration -name AdminShell -SecurityDescriptorSDDL $sddl -MaximumReceivedObjectSizeMB 20 -StartupScript C:\scripts\AdminShell.ps1

-------------------------- EXAMPLE 4 --------------------------

This example shows that a Register-PSSessionConfiguration command returns a WSManConfigContainerElement. It also shows how to find the container elements in the WSMan: drive.


 

The first command uses the Register-PSSessionConfiguration cmdlet to register the MaintenanceShell configuration. It saves the object that the cmdlet returns in the $s variable.


PS C:\> $s = Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

 

The second command displays the contents of the $s variable.


                
WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin
Name Type Keys
---- ---- ----
MaintenanceShell Container {Name=MaintenanceShell}

 

The third command uses the GetType method and its FullName property to display the type name of the object that Register-PSSessionConfiguration returns.


PS C:\> $s.GetType().FullName
                
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement

 

The fourth command uses the Format-List cmdlet to display all the properties of the object that Register-PSSessionConfiguration returns in a list. The PSPath property shows that the object is stored in a directory of the WSMan: drive.


PS C:\> $s | Format-List -Property *
                
PSPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName : MaintenanceShell
PSDrive : WSMan
PSProvider : Microsoft.WSMan.Management\WSMan
PSIsContainer : True
Keys : {Name=MaintenanceShell}
Name : MaintenanceShell
TypeNameOfElement : Container

 

The fifth command uses the Get-ChildItem cmdlet to display the items in the WSMan:\LocalHost\PlugIn path. These include the new MaintenanceShell configuration and the two default configurations that come with Windows PowerShell.


PS C:\> dir WSMan:\LocalHost\Plugin
                
Name Type Keys
---- ---- ----
MaintenanceShell Container {Name=MaintenanceShell}
microsoft.powershell Container {Name=microsoft.powershell}
microsoft.powershell32 Container {Name=microsoft.powershell32}

-------------------------- EXAMPLE 5 --------------------------

This command creates and registers the WithProfile session configuration on the local computer. The command uses the StartupScript parameter to direct Windows PowerShell to run the specified script in any session that uses the session configuration.

The content of the specified script, Add-Profile.ps1, is also displayed. The script contains a single command that uses dot sourcing to run the user's CurrentUserAllHosts profile in the current scope of the session.

For more information about profiles, see about_Profiles. For more information about dot sourcing, see about_Scopes.


PS C:\> Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1
              
# Add-Profile.ps1
. c:\users\admin01\documents\windowspowershell\profile.ps1

-------------------------- EXAMPLE 6 --------------------------

The commands in this example compare a no-language session to a restricted-language session. The example shows the effect of using the LanguageMode parameter of New-PSSessionConfigurationFile to limit the types of commands and statements that users can run in a session that uses a custom session configuration.

To run the commands in this example, start Windows PowerShell with the "Run as administrator" option. This option is required to run the Register-PSSessionConfiguration cmdlet .


 

The first pair of commands use the New-PSSessionConfigurationFile cmdlet to create two session configuration files. The first command creates a no-Language file. The second command creates a restricted-language file. Other than the value of the LanguageMode parameter, the session configuration files are equivalent.


PS C:\>New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage
PS C:\>New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode Restricted

 

The second pair of commands use the configuration files to create session configurations on the local computer.


PS C:\>Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force
PS C:\>Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force

 

The third pair of command creates two sessions, each of which uses one of the session configurations that was created in the previous command pair.


PS C:\>$NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage
PS C:\>$RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage

 

The seventh command uses the Invoke-Command cmdlet to run an If statement in the no-Language session. The command fails, because the language elements in the command are not permitted in a no-language session.


PS C:\>Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} }
The syntax is not supported by this runspace. This might be because it is in no-language mode.
+ CategoryInfo : ParserError: (if ((Get-Date) ...") {"Before"} :String) [], ParseException
+ FullyQualifiedErrorId : ScriptsNotAllowed
+ PSComputerName : localhost

 

The eighth command uses the Invoke-Command cmdlet to run the same If statement in the restricted-language session. Because these language elements are permitted in the restricted-language session, the command succeeds.


PS C:\>Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} }
Before

Related topics



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft