Tag Archives: NoServiceRestart

cmdlet, PSSessionConfiguration, Unregister

Unregister-PSSessionConfiguration

February 26, 2014 Adam

NAME
Unregister-PSSessionConfiguration

SYNOPSIS
Deletes registered session configurations from the computer.

SYNTAX
Unregister-PSSessionConfiguration [-Name] <string> [-Force] [-NoServiceRestart] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Unregister-PSSessionConfiguration cmdlet deletes registered session configurations from the computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users.

If you accidentally delete the default Microsoft.PowerShell or Microsoft.PowerShell32 session configurations, use the Enable-PSRemoting cmdlet to restore them.

PARAMETERS
-Force [<SwitchParameter>]
Suppresses 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, use the NoServiceRestart parameter.

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

-Name <string>
Specifies the names of session configurations to delete. Enter one or more configuration names. Wildcards are permitted. This parameter is required.

You can also pipe a session configuration object to Unregister-PSSessionConfiguration.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-NoServiceRestart [<SwitchParameter>]
Does not restart the WinRM service, and suppresses the prompt to restart the service.

By default, when you enter an Unregister-PSSessionConfiguration command, you are prompted to restart the WinRM service to make the change effective. Until the WinRM service is restarted, users can still use the unregistered session configuration, even though Get-PSSessionConfiguration does not find it.

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
        Accept pipeline input?     false
        Accept wildcard characters? false

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

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

-WhatIf [<SwitchParameter>]
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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration
You can pipe a session configuration object from Get-PSSessionConfiguration to Unregister-PSSessionConfiguration.

OUTPUTS
None
This cmdlet does not return any objects.

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.

————————– EXAMPLE 1 ————————–

C:\PS>Unregister-PSSessionConfiguration -Name MaintenanceShell

    Description
    ———–
    This command deletes the MaintenanceShell session configuration from the computer.

————————– EXAMPLE 2 ————————–

C:\PS>Unregister-PSSessionConfiguration -maintenanceShell -Force

    Description
    ———–
    This command deletes the MaintenanceShell session configuration from the computer. The command uses the Force parameter to suppress all user messages and to restart the WinRM service without prompting.

————————– EXAMPLE 3 ————————–

C:\PS>Unregister-PSSessionConfiguration -Name *

C:\PS> Get-PSSessionConfiguration -Name * | Unregister-PSSessionConfiguration

    Description
    ———–
    These commands delete all of the session configurations on the computer. The commands have the same effect and can be used interchangeably.

————————– EXAMPLE 4 ————————–

C:\PS>Unregister-PSSessionConfiguration -Name maintenanceShell -NoServiceRestart

C:\PS> Get-PSSessionConfiguration -Name maintenanceShell

    Get-PSSessionConfiguration -Name maintenanceShell : No Session Configuration matches criteria “maintenanceShell”.
        + CategoryInfo         : NotSpecified: (:) [Write-Error], WriteErrorException
        + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException

C:\PS> New-PSSession -configurationName MaintenanceShell

     Id Name     ComputerName    State    Configuration         Availability
     — —-     ————    —–    ————-         ————
     1 Session1 localhost     Opened MaintenanceShell     Available

C:\PS> Restart-Service winrm

    C:\PS> New-PSSession -configurationName MaintenanceShell
    [localhost] Connecting to remote server failed with the following error message : The WS-Management service cannot process the request. The resource
    URI (http://schemas.microsoft.com/powershell/MaintenanceShell) was not found in the WS-Management catalog. The catalog contains the metadata that describes resour
    ces, or logical endpoints. For more information, see the about_remote_TroubleShooting Help topic.
        + CategoryInfo         : OpenError: (System.Manageme….RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException
        + FullyQualifiedErrorId : PSSessionOpenFailed

    Description
    ———–
    This example shows the effect of using the NoServiceRestart parameter of Unregister-PSSessionConfiguration. This parameter is designed to prevent a service restart, which would disrupt any sessions on the computer.

The first command uses the Unregister-PSSessionConfiguration cmdlet to deletes the MaintenanceShell session configuration. However, because the command uses the NoServiceRestart parameter, the WinRM service is not restarted and the change is not yet completely effective.

The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session. Because the session has been removed from the WS-Management resource table, Get-PSSession cannot return it.

The third command uses the New-PSSession cmdlet to create a session on the local computer that uses the MaintenanceShell configuration. The command succeeds.

The fourth command uses the Restart-Service cmdlet to restart the WinRM service.

The fifth command again uses the New-PSSession cmdlet to create a session that uses the MaintenanceShell configuration. This time, the session fails because the MaintenanceShell configuration has been deleted.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=144308
    about_Session_Configurations
    Disable-PSSessionConfiguration
    Enable-PSSessionConfiguration
    Get-PSSessionConfiguration
    Register-PSSessionConfiguration
    Set-PSSessionConfiguration
    WS-Management Provider

cmdlet, PSSessionConfiguration, Set

Set-PSSessionConfiguration

February 26, 2014 Adam

NAME
Set-PSSessionConfiguration

SYNOPSIS
Changes the properties of a registered session configuration.

SYNTAX
Set-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-Name] <string> [-ApplicationBase <string>] [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-SecurityDescriptorSddl <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {STA | MTA | Unknown}] [-ThreadOptions {Default | UseNewThread | ReuseThread | UseCurrentThread}] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Set-PSSessionConfiguration cmdlet changes the properties of the registered session configurations on the local computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users.

Use the Name parameter to identify the configuration that you want to change. Use the other parameters to specify new values for the properties of the session configuration. To delete a property value from the configuration (and use the default value), enter an empty string (“”) or a value of $null for the corresponding parameter.

To see the properties of a session configuration, use the Get-PSSessionConfiguration cmdlet or the WS-Management Provider. For more information about the WS-Management Provider, type “Get-Help WSMan“.

PARAMETERS
-ApplicationBase <string>
Changes the path to the assembly file (*.dll) that is specified in the value of the AssemblyName parameter.

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

-AssemblyName <string>
Specifies a different assembly file for the configuration. Enter the path (optional) and file name of an assembly (.dll) file that defines the configuration type.

If you enter only the name, you can enter the path in the value of the ApplicationBase parameter.

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

-ConfigurationTypeName <string>
Specifies a different configuration type for the configuration. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class.

If you enter “$null” or an empty string, the DefaultRemotePowerShellConfiguration class is used for the session configuration.

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

-Force [<SwitchParameter>]
Suppresses 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, use the NoServiceRestart parameter.

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

-MaximumReceivedDataSizePerCommandMB <double>
Changes the limit on 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.

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

-MaximumReceivedObjectSizeMB <double>
Changes the limits on 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.

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

-Name <string>
Specifies the name of the session configuration that you want to change.

You cannot use this parameter to change the name of the session configuration.

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

-NoServiceRestart [<SwitchParameter>]
Does not restart the WinRM service, and suppresses the prompt to restart the service.

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

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

-SecurityDescriptorSddl <string>
Specifies a different 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.

To use the default security descriptor for the configuration, enter an empty string (“”) or a value of $null. The default is the root SDDL in the WSMan: drive.

If the security descriptor is complex, consider using the ShowSecurityDescriptorUI parameter instead of this one. You cannot use both parameters in the same command.

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

-ShowSecurityDescriptorUI [<SwitchParameter>]
Displays a property sheet that helps you to create a new SDDL for the session configuration. The property sheet appears after you enter the Set-PSSessionConfiguration command and then restart the WinRM service.

When setting the permissions to 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.

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

-StartupScript <string>
Adds or changes the startup script for the configuration. Enter the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration.

To delete a startup script from a session configuration, enter an empty string (“”) or a value of $null.

You can use a startup script to further configure the user’s 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.

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

-ThreadApartmentState <ApartmentState>
Changes the apartment state setting for the threads in the session. Valid values are STA, MTA and Unknown. Unknown is the default.

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

-ThreadOptions <PSThreadOptions>
Changes the thread options setting in the configuration. This setting 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.

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

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

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

-WhatIf [<SwitchParameter>]
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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
Microsoft.WSMan.Management.WSManConfigLeafElement

NOTES

To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must open Windows PowerShell with the “Run as administrator” option.

The Set-PSSessionConfiguration cmdlet does not change the configuration name and the WS-Management provider does not support the Rename-Item cmdlet. To change the name of a configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration.

You can use the Set-PSSessionConfiguration cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it.

————————– EXAMPLE 1 ————————–

C:\PS>Set-PSSessionConfiguration -Name MaintenanceShell -ThreadApartmentState STA

    Description
    ———–
    This command changes the thread apartment state in the MaintenanceShell configuration to STA. The change is effective when you restart the WinRM service.

————————– EXAMPLE 2 ————————–

C:\PS>Register-PSSessionConfiguration -Name AdminShell -assemblyName c:\shells\AdminShell.dll -configurationType AdminClass

C:\PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript AdminConfig.ps1

C:\PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript $null

    Description
    ———–
    This example shows how to create and then change a session configuration.

The first command uses the Register-PSSessionConfiguration cmdlet to create the AdminShell configuration.

The second command uses the Set-PSSessionConfiguration cmdlet to add the AdminConfig.ps1 script to the configuration. The change is effective when you restart WinRM.

The third command removes the AdminConfig.ps1 script from the configuration. It uses the Set-PSSessionConfiguration cmdlet with a value of $null for the StartupScript parameter.

————————– EXAMPLE 3 ————————–

C:\PS>Set-PSSessionConfiguration -Name foo -MaximumReceivedObjectSizeMB 20

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

    ParamName                     ParamValue
    ———                     ———-
    psmaximumreceivedobjectsizemb 20

    “Restart WinRM service”
    WinRM service need to be restarted to make the changes effective. Do you want to run the command “Restart-Service winrm”?
    [Y] Yes [N] No [S] Suspend [?] Help (default is “Y”): y

    Description
    ———–
    This example show sample output from the Set-PSSessionConfiguration cmdlet.

The Set-PSSessionConfiguration command in this example increases the value of the MaximumReceivedObjectSizeMB property to 20.

The Set-PSSessionConfiguration command returns a Microsoft.WSMan.Management.WSManConfigLeafElement object that shows the parameter name and new value.

It also prompts you to restart the WinRM service. The Set-PSSessionConfiguration change is not effective until the WinRM service is restarted.

————————– EXAMPLE 4 ————————–

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

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

    ParamName            ParamValue
    ———            ———-
    startupscript        c:\ps-test\Mainte…

C:\PS> Get-PSSessionConfiguration maintenanceshell | Format-List -property *

    xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
    Name             : MaintenanceShell
    Filename         : %windir%\system32\pwrshplugin.dll
    SDKVersion     : 1
    XmlRenderingType : text
    lang             : en-US
    PSVersion        : 2.0
    startupscript    : c:\ps-test\Maintenance.ps1
    ResourceUri     : http://schemas.microsoft.com/powershell/MaintenanceShell
    SupportsOptions : true
    ExactMatch     : true
    Capability     : {Shell}
    Permission     :

C:\PS> dir WSMan:\localhost\plugin\MaintenanceShell\InitializationParameters

    ParamName     ParamValue
    ———     ———-
    PSVersion     2.0
    startupscript c:\ps-test\Maintenance.ps1

    Description
    ———–
    This command shows different ways of viewing the results of a Set-PSSessionConfiguration command.

The first command uses the Set-PSSessionConfiguration cmdlet to change the startup script in the MaintenanceShell configuration to Maintenance.ps1. The output of this command shows the change and prompts you to restart the WinRM service. The response is “y” (yes).

The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session configuration. The command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet, which displays all of the properties of the session configuration object in a list.

The third command uses the WS-Management provider to view the initialization parameters for the MaintenanceShell configuration. The command uses the Get-ChildItem cmdlet (alias = dir) to get the child items in the InitializationParameters node for the MaintenanceShell plug-in.

For more information about the WS-Management provider, type “Get-Help WSMan“.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=144307
    about_Session_Configurations
    Disable-PSSessionConfiguration
    Enable-PSSessionConfiguration
    Get-PSSessionConfiguration
    Register-PSSessionConfiguration
    Unregister-PSSessionConfiguration
    WS-Management Provider

cmdlet, PSSessionConfiguration, Register

Register-PSSessionConfiguration

February 26, 2014 Adam

NAME
Register-PSSessionConfiguration

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>] [-SecurityDescriptorSddl <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {STA | MTA | Unknown}] [-ThreadOptions {Default | UseNewThread | ReuseThread | UseCurrentThread}] [-Confirm] [-WhatIf] [<CommonParameters>]

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 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 $PSSessionConfigurationName 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 single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration.

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

        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.

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

        Required?                    true
        Position?                    3
        Default value                System.Management.Automation.Remoting.PSSessionConfiguration
        Accept pipeline input?     false
        Accept wildcard characters? false

-Force [<SwitchParameter>]
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 <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.

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

-Name <string>
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 [<SwitchParameter>]
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.

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

-ProcessorArchitecture <string>
Specifies a processor architecture for the configuration. This value determines whether a 32-bit or 64-bit version of the process that hosts Windows PowerShell is started when the configuration is used. Valid values are x86, 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 <string>
Specifies a Security Descriptor Definition Language (SDDL) string 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 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 [<SwitchParameter>]
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.

        Required?                    false
        Position?                    named
        Default value
        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.

        Required?                    false
        Position?                    named
        Default value
        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.

        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.

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

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

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

-WhatIf [<SwitchParameter>]
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

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 and sends the XML to WS-Management, which registers the plug-in on the local computer (“New-Item WSMan:\localhost\plugin”).

————————– 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 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.

————————– 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 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 ————————–

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 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 Register-PSSessionConfiguration returns.

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

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