PowerShell Logo Small

Register-PSSessionConfiguration



This is the built-in help made by Microsoft for the command 'Register-PSSessionConfiguration', in PowerShell version 2 - as retrieved from Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates and registers a new session configuration.

SYNTAX


Register-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force]
[-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-S
ecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {STA | MTA | Unknown}] [-ThreadOptio
ns {Default | UseNewThread | ReuseThread | UseCurrentThread}] [-Confirm] [-WhatIf] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The Register-PSSessionConfiguration cmdlet creates and registers a new session configuration on the local computer. This is an advanced cmdlet t
hat is designed to be used by system administrators to manage customized session configurations for their users.

Every Windows PowerShell remote session uses a session configuration. When users create a session that connects to the computer, they can select
a configuration or use the default configurations that are registered when you enable Windows PowerShell remoting. Users can also set the $PSSess
ionConfigurationName preference variable, which specifies a default configuration for sessions created in the current session.

The session configuration configures the environment for the session. You can define the configuration by using an assembly that implements a new
configuration class and by using a script that runs in the session. The configuration can determine which commands 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 si
ngle object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration.



<

RELATED LINKS

Online version: http://go.microsoft.com/fwlink/?LinkID=144306
about_Session_Configurations
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
Set-PSSessionConfiguration
Unregister-PSSessionConfiguration
WS-Management
Provider



REMARKS

<

Examples


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

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass



Description
-----------
This command registers the NewShell session configuration. It uses the ApplicationName 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, users would type "new-pssession -configurationname newshell".








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

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1



Description
-----------
This command registers the MaintenanceShell configuration on the local computer. The command uses the StartupScript parameter to specify the Main
tenance.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 sessi
on. If the script generates any errors, including non-terminating errors, the New-PSSession command fails.








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

C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"

C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\A
dminShell.ps1



Description
-----------
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 va
riable and the MaximumReceivedObjectSizeMB parameter to increase the object size limit. It also uses the StartupScript parameter to specify a scr
ipt that configures the session.

As an alternative to using the SecurityDescriptorSDDL parameter, you can use the ShowSecurityDescriptorUI parameter, which displays a property sh
eet 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 --------------------------

C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

C:\PS> $s

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

Name Type Keys
---- ---- ----
MaintenanceShell Container {Name=MaintenanceShell}


C:\PS> $s.getType().fullname
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement


C:\PS> $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


C:\PS> dir wsman:\localhost\plugin

Name Type Keys
---- ---- ----
MaintenanceShell Container {Name=MaintenanceShell}
microsoft.powershell Container {Name=microsoft.powershell}
microsoft.powershell32 Container {Name=microsoft.powershell32}



Description
-----------
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 cm
dlet returns in the $s variable.

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

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

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.

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.








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

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

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



Description
-----------
This command creates and registers the WithProfile session configuration on the local computer. The command uses the StartupScript parameter to d
irect 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 u
ser'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.