Register-PSSession Configuration

Syntax

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>]

Description

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

Examples

Example 1: Register a NewShell session configuration

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

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 additionally configures the session.

To use this configuration, type New-PSSession -ConfigurationName newshell .

Example 2: Register a MaintenanceShell session configuration

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

This command registers the MaintenanceShell session 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. This includes 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.

Example 3: Register an AdminShell 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

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.

Example 4: Return a configuration container element

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.

PS C:\> $s



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}

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

Example 5: Register a WithProfile session configuration on the local computer

PS C:\> Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

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.

Example 6: Compare a no-language session to restricted-language session

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

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 by using the Run as administrator option. This option is required to run the Register-PSSessionConfiguration cmdlet.

Required Parameters

Optional Parameters

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

Microsoft.WSMan.Management.WSManConfigContainerElement

Notes

• To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of the Windows operating system, start Windows PowerShell by using 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.

Related Links

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration