powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Register-PSSessionConfiguration



NAME
Register-PSSessionConfiguration

SYNOPSIS
Creates and registers a new session configuration.

SYNTAX
Register-PSSessionConfiguration [-AssemblyName] [-ConfigurationTypeName] [-ApplicationBase g>] [-Name] [-Force] [-MaximumReceivedDataSizePerCommandMB ] [-MaximumReceivedObjectSizeMB >] [-NoServiceRestart] [-ProcessorArchitecture ] [-SecurityDescriptorSDDL ] [-ShowSecurityDescripto
rUI] [-StartupScript ] [-ThreadApartmentState {STA | MTA | Unknown}] [-ThreadOptions {Default | UseNewThrea
d | ReuseThread | UseCurrentThread}] [-Confirm] [-WhatIf] []


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 manage customized session conf
igurations 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 $PSSessionConfigurationName preference variable, which specifi
es 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 configuratio
n 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 single object or command.
You can also specify a security descriptor that determines the permissions that are required to use the configurati
on.


PARAMETERS
-ApplicationBase
Specifies the path to the assembly file (*.dll) that is specified in the value of the AssemblyName parameter. U
se this parameter when the value of the AssemblyName parameter does not include a path. The default is the curr
ent directory.

Required? false
Position? named
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false

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

Required? true
Position? 2
Default value None
Accept pipeline input? false
Accept wildcard characters? false

-ConfigurationTypeName
Specifies the fully qualified name of the Microsoft .NET Framework type that is used for this configuration. Th
e 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 AssemblyBa
se parameters.

Creating a type allows you to control more aspects of the session configuration, such as exposing or hiding cer
tain 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 configuratio
n.

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.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-MaximumReceivedDataSizePerCommandMB
Limits the amount of data that can be sent to this computer in any single remote command. Enter the data size i
n megabytes (MB). The default is 50 MB.

If a data size limit is defined in the configuration type that is specified in the ConfigurationTypeName parame
ter, the limit in the configuration type is used and the value of this parameter is ignored.

Required? false
Position? named
Default value 50
Accept pipeline input? false
Accept wildcard characters? false

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

If an object size limit is defined in the configuration type that is specified in the ConfigurationTypeName par
ameter, the limit in the configuration type is used and the value of this parameter is ignored.

Required? false
Position? named
Default value 10
Accept pipeline input? false
Accept wildcard characters? false

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

Required? true
Position? 1
Default value None
Accept pipeline input? false
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 ser
vice to make the new session configuration effective. Until the WinRM service is restarted, the new session co
nfiguration 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.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-ProcessorArchitecture
Specifies a processor architecture for the configuration. This value determines whether a 32-bit or 64-bit vers
ion of the process that hosts Windows PowerShell is started when the configuration is used. Valid values are x8
6, AMD64, and IA64.

The default is determined by the processor architecture of the computer that hosts the session configuration.

Required? false
Position? named
Default value The processor architecture of the host computer.
Accept pipeline input? false
Accept wildcard characters? false

-SecurityDescriptorSDDL
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 pa
rameter. 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 chan
ge the root SDDL, use the WS-Management provider. For example "get-item wsman:\localhost\service\rootSDDL". For
more information about the WS-Management provider, type "get-help wsman".

Required? false
Position? named
Default value The value of the root SDDL
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 a
ppears 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)" pe
rmission to use the session configuration in a session.

You cannot use the SecurityDescriptorSDDL parameter and this parameter in the same command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-StartupScript
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-terminati
ng error), the session is not created and the user's New-PSSession command fails.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ThreadApartmentState
Determines the apartment state of the threads in the session. Valid values are STA, MTA, and Unknown. Unknown i
s the default.

Required? false
Position? named
Default value Unknown
Accept pipeline input? false
Accept wildcard characters? false

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

Required? false
Position? named
Default value UseCurrentThread
Accept pipeline input? false
Accept wildcard characters? false

-Confirm []
Prompts you for confirmation before executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WhatIf []
Describes what would happen if you executed the command without actually executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

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 Windows, you must 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 a
nd sends the XML to WS-Management, which registers the plug-in on the local computer ("new-item wsman:\localhos
t\plugin").


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

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


Description
-----------
This command registers the NewShell session configuration. It uses the ApplicationName and ApplicationBase paramete
rs to specify the location of the MyShell.dll file, which specifies the cmdlets and providers in the session config
uration. It also uses the ConfigurationTypeName parameter to specify a new class that further configures the sessio
n.

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 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 PowerSh
ell snap-ins, and setting the execution policy for the session. If the script generates any errors, including non-t
erminating 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\AdminShell.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 SDD
L in the value of the $sddl variable and the MaximumReceivedObjectSizeMB parameter to increase the object size limi
t. 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 --------------------------

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 sh
ows how to find the container elements in the WSMan: drive.

The first command uses the Register-PSSessionConfiguration cmdlet to register the MaintenanceShell configuration. I
t saves the object that the cmdlet 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 Reg
ister-PSSessionConfiguration returns.

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

The fifth command uses the Get-ChildItem cmdlet to display the items in the WSMan:\LocalHost\PlugIn path. These inc
lude 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 th
e StartupScript parameter to direct Windows PowerShell to run the specified script in any session that uses the ses
sion 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.






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