powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Unregister-PSSessionConfiguration



NAME
Unregister-PSSessionConfiguration

SYNOPSIS
Deletes registered session configurations from the computer.

SYNTAX
Unregister-PSSessionConfiguration [-Name] [-Force] [-NoServiceRestart] [-Confirm] [-WhatIf] [ ters>]


DESCRIPTION
The Unregister-PSSessionConfiguration cmdlet deletes registered session configurations from the computer. This is a
n 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 t
he Enable-PSRemoting cmdlet to restore them.


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.

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

-Name
Specifies the names of session configurations to delete. Enter one or more configuration names. Wildcards are p
ermitted. 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 []
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 unregister
ed 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 []
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
Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration
You can pipe a session configuration object from Get-PSSessionConfiguration to Unregister-PSSessionConfiguratio
n.


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 param
eter 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 cata
log 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) [], PSRemotingTransport
Exception
+ FullyQualifiedErrorId : PSSessionOpenFailed


Description
-----------
This example shows the effect of using the NoServiceRestart parameter of Unregister-PSSessionConfiguration. This pa
rameter 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 configu
ration. However, because the command uses the NoServiceRestart parameter, the WinRM service is not restarted and th
e change is not yet completely effective.

The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session. Because the sess
ion 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 Maintenance
Shell 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 configurat
ion. 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