Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Unregister-PSSessionConfiguration

Published: February 29, 2012

Updated: August 15, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

Unregister-PSSessionConfiguration

Deletes registered session configurations from the computer.

Syntax

Parameter Set: Default
Unregister-PSSessionConfiguration [-Name] <String> [-Force] [-NoServiceRestart] [-Confirm] [-WhatIf] [ <CommonParameters>]




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

To make the change effective, Unregister-PSSessionConfiguration restarts the WinRM service. To prevent the restart, use the NoServiceRestart parameter.

If you accidentally delete the default Microsoft.PowerShell or Microsoft.PowerShell32 session configurations, use the Enable-PSRemoting function to restore them. For more information, see about_Session_Configurations.

Parameters

-Force

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.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Name<String>

Specifies the names of the session configurations to delete. Enter one session configuration name or a configuration name pattern. Wildcards are permitted. This parameter is required.

You can also pipe a session configurations to Unregister-PSSessionConfiguration.


Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

true

-NoServiceRestart

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.


Aliases

none

Required?

false

Position?

named

Default Value

none

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.

  • Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration

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


Outputs

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

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

Examples

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

This command deletes the MaintenanceShell session configuration from the computer.


PS C:\> unregister-pssessionconfiguration -name MaintenanceShell

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

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.


PS C:\> unregister-pssessionconfiguration -name MaintenanceShell -force

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

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


PS C:\> unregister-pssessionconfiguration -name *
PS C:\>get-pssessionconfiguration -name * | unregister-pssessionconfiguration

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

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.


PS C:\> unregister-pssessionconfiguration -name maintenanceShell -noServiceRestart
PS C:\>get-pssessionconfiguration -name maintenanceShell

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

PS C:\>new-pssession -configurationName MaintenanceShell

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

PS C:\>restart-service winrm
PS C:\>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 resources, or logical endpoints. For more information, see the about_Remote_Troubleshooting Help topic.
+ CategoryInfo          : OpenError: (System.Manageme....RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException
+ FullyQualifiedErrorId : PSSessionOpenFailed

Related topics



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.