##Add-Computer
###SYNOPSIS Add the local computer to a domain or workgroup.
###SYNTAX TODO
###DESCRIPTION The Add-Computer cmdlet adds the local computer or remote computers to a domain or workgroup, or moves them from one domain to another. It also creates a domain account if the computer is added to the domain without an account. You can use the parameters of this cmdlet to specify an organizational unit (OU) and domain controller or to perform an unsecure join. To get the results of the command, use the Verbose and PassThru parameters.
###PARAMETERS
####ComputerName [<String[]>]
Specifies the computers to add to a domain or workgroup. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of each of the remote computers. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Add-Computer even if your computer is not configured to run remote commands. This parameter is introduced in Windows PowerShell 3.0.
####Credential <PSCredential>
Specifies a user account that has permission to join the computers to a new domain. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. To specify a user account that has permission to remove the computer from its current domain, use the UnjoinDomainCredential parameter. To specify a user account that has permission to connect to a remote computer, use the LocalCredential parameter.
####DomainName <String>
Specifies the domain to which the computers are added. This parameter is required when adding the computers to a domain.
####Force [<SwitchParameter>]
Suppresses the user confirmation prompt. Without this parameter, Add-Computer requires you to confirm the addition of each computer. This parameter is introduced in Windows PowerShell 3.0.
####LocalCredential [<PSCredential>]
Specifies a user account that has permission to connect to the computers that are specified by the ComputerName parameter. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. To specify a user account that has permission to add the computers to a new domain, use the Credential parameter. To specify a user account that has permission to remove the computers from their current domain, use the UnjoinDomainCredential parameter. This parameter is introduced in Windows PowerShell 3.0.
####NewName [<String>]
Specifies a new name for the computer in the new domain. This parameter is valid only when one computer is being added or moved. This parameter is introduced in Windows PowerShell 3.0.
####OUPath [<String>]
Specifies an organizational unit (OU) for the domain account. Enter the full distinguished name of the OU in quotation marks. The default value is the default OU for machine objects in the domain.
####PassThru [<SwitchParameter>]
Returns the results of the command. By default, this cmdlet does not generate any output.
####Restart [<SwitchParameter>]
Restarts the computers that were added to the domain or workgroup. A restart is often required to make the change effective. This parameter is introduced in Windows PowerShell 3.0.
####Server [<String>]
Specifies the name of a domain controller that adds the computer to the domain. Enter the name in DomainName\ComputerName format. By default, no domain controller is specified.
####UnjoinDomainCredential [<PSCredential>]
Specifies a user account that has permission to remove the computers from their current domains. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. Use this parameter when you are moving computers to a different domain. To specify a user account that has permission to join the new domain, use the Credential parameter. To specify a user account that has permission to connect to a remote computer, use the LocalCredential parameter. This parameter is introduced in Windows PowerShell 3.0.
####Options [<JoinOptions>]
Sets advanced options for the Add-Computer join operation. Enter one or more values in a comma-separated string. Valid values are:
{-- AccountCreate: Creates a domain account. The Add-Computer cmdlet automatically creates ... {For more information about these options, see "NetJoinDomain" on , at http://msdn.microso... This parameter is introduced in Windows PowerShell 3.0.
####Unsecure [<SwitchParameter>]
Performs an unsecure join to the specified domain.
####WorkgroupName <String>
Specifies the name of a workgroup to which the computers are added. The default value is "WORKGROUP".
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.String You can pipe computer names and new names to the Add-ComputerCmdlet.
###OUTPUTS ####Microsoft.PowerShell.Commands.ComputerChangeInfo When you use the PassThru parameter, Add-Computer returns a ComputerChangeInfo object. Otherwise, this cmdlet does not generate any output.
###NOTES ####Microsoft.PowerShell.Commands.ComputerChangeInfo In Windows PowerShell 2.0, the Server parameter of Add-Computer fails even when the server is present. In Windows PowerShell 3.0, the implementation of the Server parameter is changed so that it works reliably.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Add-Computer -DomainName Domain01 -Restart
This command adds the local computer to the Domain01 domain and then restarts the computer to make the change effective. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Add-Computer -WorkGroupName WORKGROUP-A
This command adds the local computer to the Workgroup-A workgroup. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Add-Computer -DomainName Domain01 -Server Domain01\DC01 -Passthru -Verbose
This command adds the local computer to the Domain01 domain by using the Domain01\DC01 domain controller. The command uses the PassThru and Verbose parameters to get detailed information about the results of the command. -------------------------- EXAMPLE 4 --------------------------
PS C:\>Add-Computer -DomainName Domain02 -OUPath "OU=testOU,DC=domain,DC=Domain,DC=com"
This command adds the local computer to the Domain02 domain. It uses the OUPath parameter to specify the organizational unit for the new accounts. -------------------------- EXAMPLE 5 --------------------------
PS C:\>Add-Computer -ComputerName Server01 -LocalCredential Server01\Admin01 -DomainName Domain02 -Credential Domain02\Admin02 -Restart -Force
This command adds the Server01 computer to the Domain02 domain. It uses the LocalCredential parameter to specify a user account that has permission to connect to the Server01 computer. It uses the Credential parameter to specify a user account that has permission to join computers to the domain. It uses the Restart parameter to restart the computer after the join operation completes and the Force parameter to suppress user confirmation messages. -------------------------- EXAMPLE 6 --------------------------
PS C:\>Add-Computer -ComputerName Server01, Server02, localhost -Domain Domain02 -LocalCredential Domain01\User01 -UnjoinDomainCredential Domain01\Admin01 -Credential Domain02\Admin01 -Restart
This command moves the Server01 and Server02 computers, and the local computer, from Domain01 to Domain02. It uses the LocalCredential parameter to specify a user account that has permission to connect to the three affected computers. It uses the UnjoinDomainCredential parameter to specify a user account that has permission to unjoin the computers from the Domain01 domain and the Credential parameter to specify a user account that has permission to join the computers to the Domain02 domain. It uses the Restart parameter to restart all three computers after the move is complete. -------------------------- EXAMPLE 7 --------------------------
PS C:\>Add-Computer -ComputerName Server01 -Domain Domain02 -NewName Server044 -Credential Domain02\Admin01 -Restart
This command moves the Server01 computer to the Domain02 and changes the machine name to Server044. The command uses the credential of the current user to connect to the Server01 computer and unjoin it from its current domain. It uses the Credential parameter to specify a user account that has permission to join the computer to the Domain02 domain. -------------------------- EXAMPLE 8 --------------------------
PS C:\>Add-Computer -ComputerName (Get-Content Servers.txt) -Domain Domain02 -Credential Domain02\Admin02 -Options Win9xUpgrade -Restart
This command adds the computers that are listed in the Servers.txt file to the Domain02 domain. It uses the Options parameter to specify the Win9xUpgrade option. The Restart parameter restarts all of the newly added computers after the join operation completes.
###RELATED LINKS Online Version: Checkpoint-Computer Remove-Computer Restart-Computer Rename-Computer Restore-Computer Stop-Computer Test-Connection ##Add-Content
###SYNOPSIS Adds content to the specified items, such as adding words to a file.
###SYNTAX TODO
###DESCRIPTION The Add-Content cmdlet appends content to a specified item or file. You can specify the content by typing the content in the command or by specifying an object that contains the content.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Overrides the read-only attribute, allowing you to add content to a read-only file.
####Include [<String[]>]
Adds only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to the items that receive the additional content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Returns an object representing the added content. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the items that receive the additional content. Wildcards are permitted. If you specify multiple paths, use commas to separate the paths.
####Value <Object[]>
Specifies the content to be added. Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. You cannot specify the contents of a file by typing its path, because the path is just a string, but you can use a Get-Content command to get the content and pass it to the Value parameter.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.Object You can pipe the objects to be added (the Value) to Add-Content.
###OUTPUTS ####None or System.String When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.String When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. The Add-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>add-content -path *.txt -exclude help* -value "END"
This command adds "END" to all text files in the current directory, except for those with file names that begin with "help".
-------------------------- EXAMPLE 2 --------------------------
PS C:\>add-content -Path file1.log, file2.log -Value (get-date) -passthru
This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>add-content -path monthly.txt -value (get-content c:\rec1\weekly.txt)
This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. In that case, the command would be "add-content -path monthly.txt -value $w".
-------------------------- EXAMPLE 4 --------------------------
PS C:\>add-content -value (get-content test.log) -path C:\tests\test134\logs\test134.log
This command creates a new directory and file and copies the content of an existing file to the newly created file. This command uses the Add-Content cmdlet to add the content. The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. The Force parameter is not required for this command. Add-Content creates directories to complete a path even without the Force parameter.
###RELATED LINKS Online Version: Clear-Content Get-Content Get-Item Set-Content about_Providers ##Checkpoint-Computer
###SYNOPSIS Creates a system restore point on the local computer.
###SYNTAX TODO
###DESCRIPTION The Checkpoint-Computer cmdlet creates a system restore point on the local computer. System restore points and the Checkpoint-Computer cmdlet are supported only on client operating systems, such as Windows 8, Windows 7, Windows Vista, and Windows XP. Beginning in Windows 8, Checkpoint-Computer cannot create more than one checkpoint each day.
###PARAMETERS
####Description <String>
Specifies a descriptive name for the restore point. This parameter is required.
####RestorePointType [<String>]
Specifies the type of restore point. The default is APPLICATION_INSTALL. Valid values are APPLICATION_INSTALL, APPLICATION_UNINSTALL, DEVICE_DRIVER_INSTALL, MODIFY_SETTINGS, and CANCELLED_OPERATION.
###INPUTS ####None You cannot pipe objects to Checkpoint-Computer.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None This cmdlet uses the CreateRestorePoint method of the SystemRestore class with a BEGIN_SYSTEM_CHANGE event. Beginning in Windows 8, Checkpoint-Computer cannot create more than one system restore point each day. If you try to create a new restore point before the 24-hour period has elapsed, Windows PowerShell generates the following error: "A new system restore point cannot be created because one has already been created within the past 24 hours. Please try again later."
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Checkpoint-Computer -Description "Install MyApp"
This command creates a system restore point called "Install MyApp". It uses the default APPLICATION_INSTALL restore point type.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Checkpoint-Computer -Description "ChangeNetSettings" -RestorePointType MODIFY_SETTINGS
This command creates a MODIFY_SETTINGS system restore point called "ChangeNetSettings".
###RELATED LINKS Online Version: Disable-ComputerRestore Enable-ComputerRestore Get-ComputerRestorePoint Restore-Computer ##Clear-Content
###SYNOPSIS Deletes the contents of an item, but does not delete the item.
###SYNTAX TODO
###DESCRIPTION The Clear-Content cmdlet deletes the contents of an item, such as deleting the text from a file, but it does not delete the item. As a result, the item exists, but it is empty. Clear-Content is similar to Clear-Item, but it works on items with contents, instead of items with values.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to clear the file contents even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Clears only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the paths to the items from which content is deleted. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the paths to the items from which content is deleted. Wildcards are permitted. The paths must be paths to items, not to containers. For example, you must specify a path to one or more files, not a path to a directory. Wildcards are permitted. This parameter is required, but the parameter name ("Path") is optional.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe objects to Clear-Content.
###OUTPUTS ####None This cmdlet does not return any objects.
###NOTES ####None You can also refer to Clear-Content by its built-in alias, "clc". For more information, see about_Aliases. If you omit the -Path parameter name, the value of Path must be the first parameter in the command. For example, "clear-content c:\mydir*.txt". If you include the parameter name, you can list the parameters in any order. You can use Clear-Content with the Windows PowerShell FileSystem provider and with other providers that manipulate content. To clear items that are not considered to be content, such as items managed by the Windows PowerShell Certificate or Registry providers, use Clear-Item. The Clear-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>clear-content ..\SmpUsers\*\init.txt
This command deletes all of the content from the "init.txt" files in all subdirectories of the SmpUsers directory. The files are not deleted, but they are empty.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>clear-content -path * -filter *.log -force
This command deletes the contents of all files in the current directory with the ".log" file name extension, including files with the read-only attribute. The asterisk () in the path represents all items in the current directory. The Force parameter makes the command effective on read-only files. Using a filter to restrict the command to files with the ".log" file name extension instead of specifying ".log" in the path makes the operation faster.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>clear-content c:\Temp\* -Include Smp* -Exclude *2* -whatif
This command requests a prediction of what would happen if you submitted the command: "clear-content c:\temp* -include smp* -exclude 2". The result lists the files that would be cleared; in this case, files in the Temp directory whose names begin with "Smp", unless the file names include a "2". To execute the command, run it again without the Whatif parameter.
###RELATED LINKS Online Version: Add-Content Get-Content Get-Item Set-Content about_Providers ##Clear-EventLog
###SYNOPSIS Deletes all entries from specified event logs on the local or remote computers.
###SYNTAX TODO
###DESCRIPTION The Clear-EventLog cmdlet deletes all of the entries from the specified event logs on the local computer or on remote computers. To use Clear-EventLog, you must be a member of the Administrators group on the affected computer. The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.
###PARAMETERS
####ComputerName [<String[]>]
Specifies a remote computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-EventLog even if your computer is not configured to run remote commands.
####LogName <String[]>
Specifies the event logs. Enter the log name (the value of the Log property; not the LogDisplayName) of one or more event logs, separated by commas. Wildcard characters are not permitted. This parameter is required.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe objects to Clear-EventLog.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None To use Clear-EventLog on Windows Vista and later versions of Windows, start Windows PowerShell with the "Run as administrator" option.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>clear-eventlog "Windows PowerShell"
This command deletes the entries from the "Windows PowerShell" event log on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>clear-eventlog -logname ODiag, OSession -computername localhost, Server02
This command deletes all of the entries in the Microsoft Office Diagnostics (ODiag) and Microsoft Office Sessions (OSession) logs on the local computer and the Server02 remote computer.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>clear-eventlog -log application, system -confirm
This command prompts you for confirmation before deleting the entries in the specified event logs.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>function clear-all-event-logs ($computerName="localhost")
{
$logs = get-eventlog -computername $computername -list | foreach {$_.Log}
$logs | foreach {clear-eventlog -comp $computername -log $_ }
get-eventlog -computername $computername -list
}
PS C:\>clear-all-event-logs -comp Server01
Max(K) Retain OverflowAction Entries Log
------ ------ -------------- ------- ---
15,168 0 OverwriteAsNeeded 0 Application
15,168 0 OverwriteAsNeeded 0 DFS Replication
512 7 OverwriteOlder 0 DxStudio
20,480 0 OverwriteAsNeeded 0 Hardware Events
512 7 OverwriteOlder 0 Internet Explorer
20,480 0 OverwriteAsNeeded 0 Key Management Service
16,384 0 OverwriteAsNeeded 0 Microsoft Office Diagnostics
16,384 0 OverwriteAsNeeded 0 Microsoft Office Sessions
30,016 0 OverwriteAsNeeded 1 Security
15,168 0 OverwriteAsNeeded 2 System
15,360 0 OverwriteAsNeeded 0 Windows PowerShell
This function clears all event logs on the specified computers and then displays the resulting event log list. Notice that a few entries were added to the System and Security logs after the logs were cleared but before they were displayed.
###RELATED LINKS Online Version: Get-EventLog Limit-EventLog New-EventLog Remove-EventLog Show-EventLog Write-EventLog ##Clear-Item
###SYNOPSIS Deletes the contents of an item, but does not delete the item.
###SYNTAX TODO
###DESCRIPTION The Clear-Item cmdlet deletes the value of an item, but it does not delete the item. For example, Clear-Item can delete the value of a variable, but it does not delete the variable. The value that used to represent a cleared item is defined by each Windows PowerShell provider. Clear-Item is similar to Clear-Content, but it works on aliases and variables, instead of files.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to clear items that cannot otherwise be changed, such as read- only aliases. The cmdlet cannot clear constants. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Clears only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to the items being cleared. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the path to the items being cleared. Wildcards are permitted. This parameter is required, but the parameter name ("Path") is optional.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a path string to Clear-Item.
###OUTPUTS ####None This cmdlet does not return any objects.
###NOTES ####None The Clear-Item cmdlet is supported only by several Windows PowerShell providers, including the Alias, Environment, Function, Registry, and Variable providers. As such, you can use Clear-Item to delete the content of items in the provider namespaces. You cannot use Clear-Item to delete the contents of a file, because the Windows PowerShell FileSystem provider does not support this cmdlet. To clear files, use Clear-Content. You can also refer to Clear-Item by its built-in alias, "cli". For more information, type "get-help about_Aliases". The Clear-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Clear-Item Variable:TestVar1
-or-
PS C:>Set-location Variable:PS Variable:\> Clear-Item Testvar1
This command deletes the value of the variable, Testvar1. The variable remains and is valid, but its value is set to null. The variable name is prefixed with "Variable:" to indicate the Windows PowerShell Variable provider. The alternate commands show that, to get the same result, you can switch to the Windows PowerShell Variable: drive and then run the Clear-Item command.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Clear-Item Alias:log* -Include *1* -Exclude *3* -Whatif
What if: Performing operation "Clear Item" on Target "Item: log1".
This command asks Windows PowerShell what would happen if you executed the command, "clear-item alias:log* -include 1 -exclude *3". In response, Windows PowerShell explains that it would delete the value of the log1 alias, but the command would not have any effect on the log, log2, or log13 aliases. Because the Alias provider does not permit an alias without a value, when you clear an alias, you also delete the alias. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Clear-Item HKLM:\Software\MyCompany\MyKey -Confirm
This command deletes all registry entries in the MyKey subkey, but only after prompting you to confirm your intent. It does not delete the MyKey subkey or affect any other registry keys or entries. You can use the Include and Exclude parameters to identify particular registry keys, but you cannot use them to identify registry entries. To delete particular registry entries, use the Remove-ItemProperty cmdlet. To delete the value of a registry entry, use the Clear-ItemPropertycmdlet.
###RELATED LINKS Online Version: Copy-Item Get-Item Invoke-Item Move-Item New-Item Remove-Item Rename-Item Set-Item about_Providers ##Clear-ItemProperty
###SYNOPSIS Deletes the value of a property but does not delete the property.
###SYNTAX TODO
###DESCRIPTION The Clear-ItemProperty cmdlet deletes the value of a property, but it does not delete the property. You can use this cmdlet to delete the data from a registry value.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as ".txt" or "s". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to delete properties from items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_Providers.
####Include [<String[]>]
Clears only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to the property being cleared. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String>
Specifies the name of the property to be cleared, such as the name of a registry value. Wildcards are not permitted.
####PassThru [<SwitchParameter>]
Returns an object representing the cleared item's property. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the property being cleared. Wildcards are permitted.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a path string to Clear-ItemProperty.
###OUTPUTS ####None or System.Management.Automation.PSCustomObject When you use the PassThru parameter, Clear-ItemProperty generates a PSCustomObject object that represents the cleared item property. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PSCustomObject You can use Clear-ItemProperty to delete the data in registry values without deleting the value. If the data type of the value is Binary or DWORD, clearing the data sets the value to zero. Otherwise, the value is empty. You can also refer to Clear-ItemProperty by its built-in alias, "clp". For more information, see about_Aliases. The Clear-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>clear-itemproperty -path HKLM:\Software\MyCompany\MyApp -name Options
This command deletes the data in the Options registry value in the MyApp subkey of HKEY_LOCAL_MACHINE\Software\MyCompany. Because the command is being issued from a file system drive (C:), it uses the fully qualified path to the HKLM: drive and the Software\MyCompany\MyApp subkey. It uses the Name parameter to specify the Options value.
###RELATED LINKS Online Version: Copy-ItemProperty Get-ItemProperty Move-ItemProperty New-ItemProperty Rename-ItemProperty about_Providers ##Complete-Transaction
###SYNOPSIS Commits the active transaction.
###SYNTAX TODO
###DESCRIPTION The Complete-Transaction cmdlet commits an active transaction. When you commit a transaction, the commands in the transaction are finalized and the data affected by the commands is changed. If the transaction includes multiple subscribers, to commit the transaction, you must enter one Complete-Transaction command for every Start-Transaction command. The Complete-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_Transactions.
###PARAMETERS
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe objects to Complete-Transaction.
###OUTPUTS ####None This cmdlet does not return any objects.
###NOTES ####None You cannot roll back a transaction that has been committed, or commit a transaction that has been rolled back. You cannot roll back any transaction other than the active transaction. To roll back a different transaction, you must first commit or roll back the active transaction. By default, if any part of a transaction cannot be committed, such as when a command in the transaction results in an error, the entire transaction is rolled back.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> dir m*
Hive: HKEY_CURRENT_USER\software
SKC VC Name Property
--- -- ---- --------
82 1 Microsoft {(default)}
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
82 1 Microsoft {(default)}
0 0 MyCompany {}
This example shows the effect of using the Complete-Transaction cmdlet to commit a transaction. The Start-Transaction command starts the transaction. The New-Item command uses the UseTransaction parameter to include the command in the transaction. The first "dir" (Get-ChildItem) command shows that the new item has not yet been added to the registry. The Complete-Transaction command commits the transaction, which makes the registry change effective. As a result, the second "dir" command shows that the registry is changed.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany {}
PS HKCU:\software> start-transaction
PS HKCU:\Software> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 Active
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value -UseTransaction
MyKey
-----
123
PS HKCU:\software> complete-transaction
PS HKCU:\software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
PS HKCU:\software> dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
82 1 Microsoft {(default)}
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
82 1 Microsoft {(default)}
0 1 MyCompany {MyKey}
This example shows how to use Complete-Transaction to commit a transaction that has more than one subscriber. To commit a multi-subscriber transaction, you must enter one Complete-Transaction command for every Start-Transaction command. The data is changed only when the final Complete-Transaction command is submitted. For demonstration purposes, this example shows a series of commands entered at the command line. In practice, transactions are likely to be run in scripts, with the secondary transaction being run by a function or helper script that is called by the main script. In this example, a Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter adds the MyCompany key to the Software key. Although the New-Item command returns a key object, the data in the registry is not yet changed. A second Start-Transaction command adds a second subscriber to the existing transaction. The Get-Transaction command confirms that the subscriber count is 2. A New-ItemProperty command with the UseTransaction parameter adds a registry entry to the new MyCompany key. Again, the command returns a value, but the registry is not changed. The first Complete-Transaction command reduces the subscriber count by 1. This is confirmed by a Get-Transaction command. However, no data is changed, as evidenced by a "dir m*" (Get-ChildItem) command. The second Complete-Transaction command commits the entire transaction and changes the data in the registry. This is confirmed by a second "dir m*" command, which shows the changes.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
82 1 Microsoft {(default)}
PS HKCU:\software> dir m* -UseTransaction
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
82 1 Microsoft {(default)}
0 0 MyCompany {}
PS HKCU:\software> complete-transaction
This example shows the value of using Get-* commands, and other commands that do not change data, in a transaction. When a Get-* command is used in a transaction, it gets the objects that are part of the transaction. This allows you to preview the changes in the transaction before the changes are committed. In this example, a transaction is started. A New-Item command with the UseTransaction parameter adds a new key to the registry as part of the transaction. Because the new registry key is not added to the registry until the Complete-Transaction command is run, a simple "dir" (Get-ChildItem) command shows the registry without the new key. However, when you add the UseTransaction parameter to the "dir" command, the command becomes part of the transaction, and it gets the items in the transaction even if they are not yet added to the data.
###RELATED LINKS Online Version: Get-Transaction Start-Transaction Undo-Transaction Use-Transaction about_Transactions ##Convert-Path
###SYNOPSIS Converts a path from a Windows PowerShell path to a Windows PowerShell provider path.
###SYNTAX TODO
###DESCRIPTION The Convert-Path cmdlet converts a path from a Windows PowerShell path to a Windows PowerShell provider path.
###PARAMETERS
####LiteralPath <String[]>
Specifies the path to be converted. The value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the Windows PowerShell path to be converted.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a path (but not a literal path) to Convert-Path.
###OUTPUTS ####System.String Convert-Path returns a string that contains the converted path.
###NOTES ####System.String The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators. You can use the path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers. The Convert-Path cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>convert-path .
This command converts the current working directory, which is represented by a dot (.), to a standard file system path.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>convert-path HKLM:\software\microsoft
This command converts the Windows PowerShell provider path to a standard registry path.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>convert-path ~
C:\Users\User01
This command converts the path to the home directory of the current provider, which is the FileSystem provider, to a string.
###RELATED LINKS Online Version: Join-Path Resolve-Path Split-Path Test-Path about_Providers ##Copy-Item
###SYNOPSIS Copies an item from one location to another.
###SYNTAX TODO
###DESCRIPTION The Copy-Item cmdlet copies an item from one location to another location in the same namespace. For example, it can copy a file to a folder, but it cannot copy a file to a certificate drive. Copy-Item does not cut or delete the items being copied. The particular items that the cmdlet can copy depend on the Windows PowerShell provider that exposes the item. For example, it can copy files and directories in a file system drive and registry keys and entries in the registry drive. Copy-Item can copy and rename items in the same command. To rename an item, enter the new name in the value of the Destination parameter. To rename an item without copying it, use the Rename-Item cmdlet.
###PARAMETERS
####Container [<SwitchParameter>]
Preserves container objects during the copy operation.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Destination [<String>]
Specifies the path to the new location. To rename a copied item, include the new name in the value.
####Exclude [<String[]>]
Omits the specified items. Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to copy items that cannot otherwise be changed, such as copying over a read-only file or alias.
####Include [<String[]>]
Specifies only those items upon which the cmdlet will act, excluding all others.
####LiteralPath <String[]>
Specifies a path to the item. The value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Returns an object representing each copied item. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the items to copy.
####Recurse [<SwitchParameter>]
Specifies a recursive copy.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Copy-ItemProperty.
###OUTPUTS ####None or an object representing the copied item. When you use the PassThru parameter, Copy-Item returns an object that represents the copied item. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or an object representing the copied item. Copy-Item is like the 'cp' or 'copy' commands in other shells. The Copy-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Copy-Item C:\Wabash\Logfiles\mar1604.log.txt -Destination C:\Presentation
This command copies the mar1604.log.txt file to the C:\Presentation directory. The command does not delete the original file.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Copy-Item C:\Logfiles -Destination C:\Drawings -Recurse
This command copies the entire contents of the Logfiles directory into the Drawings directory. If the LogFiles directory contains files in subdirectories, those subdirectories will be copied with their file trees intact. The Container parameter is set to true by default. This preserves the directory structure.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse
This command copies the contents of the C:\Logfiles directory to the C:\Drawings\Logs directory. It creates the \Logs subdirectory if it does not already exist.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>Copy-Item \\Server01\Share\Get-Widget.ps1 -Destination \\Server12\ScriptArchive\Get-Widget.ps1.txt
This command uses the Copy-Item cmdlet to copy the Get-Widget.ps1 script from the \Server01\Share directory to the \Server12\ScriptArchive directory. As part of the copy operation, the command also changes the item name from Get-Widget.ps1 to Get-Widget.ps1.txt, so it can be attached to email messages.
###RELATED LINKS Online Version: Clear-Item Get-Item Invoke-Item Move-Item New-Item Remove-Item Rename-Item Set-Item about_Providers ##Copy-ItemProperty
###SYNOPSIS Copies a property and value from a specified location to another location.
###SYNTAX TODO
###DESCRIPTION The Copy-ItemProperty cmdlet copies a property and value from a specified location to another location. For example, you can use Copy-ItemProperty to copy one or more registry entries from one registry key to another registry key.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Destination <String>
Specifies the path to the destination location.
####Exclude [<String[]>]
Omits the specified items. Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to override restrictions such as renaming existing files as long as security is not compromised.
####Include [<String[]>]
Specifies only those items upon which the cmdlet will act, excluding all others.
####LiteralPath <String[]>
Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String>
Specifies the name of the property to be copied.
####PassThru [<SwitchParameter>]
Returns an object representing the copied item property. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the property to be copied.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Copy-ItemProperty.
###OUTPUTS ####None or System.Management.Automation.PSCustomObject When you use the Passthru parameter, Copy-ItemProperty generates a PsCustomObject representing the copied item property. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PSCustomObject The Copy-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>copy-itemproperty -path MyApplication -destination HKLM:\Software\MyApplicationRev2 -name MyProperty
This command copies the property named MyProperty from the MyApplication registry key to the MyApplicationRev2 registry key.
###RELATED LINKS Online Version: Clear-ItemProperty Get-ItemProperty Move-ItemProperty New-ItemProperty Rename-ItemProperty Set-ItemProperty about_Providers ##Debug-Process
###SYNOPSIS Debugs one or more processes running on the local computer.
###SYNTAX TODO
###DESCRIPTION The Debug-Process cmdlet attaches a debugger to one or more running processes on a local computer. You can specify the processes by their process name or process ID (PID), or you can pipe process objects to Debug-Process. Debug-Process attaches the debugger that is currently registered for the process. Before using this cmdlet, verify that a debugger is downloaded and correctly configured.
###PARAMETERS
####Id <Int32[]>
Specifies the process IDs of the processes to be debugged. The parameter name ("-Id") is optional. To find the process ID of a process, type "get-process".
####InputObject <Process[]>
Specifies the process objects that represent processes to be debugged. Enter a variable that contains the process objects or a command that gets the process objects, such as a Get-Process command. You can also pipe process objects to Debug-Process.
####Name <String[]>
Specifies the names of the processes to be debugged. If there is more than one process with the same name, Debug-Process attaches a debugger to all processes with that name. The parameter name ("Name") is optional.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.Int32, System.Diagnostics.Process, System.String You can pipe a process ID (Int32), a process object (System.Diagnostics.Process), or a process name (String) to Debug-Process.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None This cmdlet uses the AttachDebugger method of the Windows Management Instrumentation (WMI) Win32_Process class. For more information about this method, see "AttachDebugger Method" in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=143640.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>debug-process -name powershell
This command attaches a debugger to the PowerShell process on the computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>debug-process -name sql*
This command attaches a debugger to all processes that have names that begin with "sql".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>debug-process winlogon, explorer, outlook
This command attaches a debugger to the Winlogon, Explorer, and Outlook processes.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>debug-process -id 1132, 2028
This command attaches a debugger to the processes that have process IDs 1132 and 2028.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>get-process powershell | debug-process
This command attaches a debugger to the PowerShell processes on the computer. It uses the Get-Process cmdlet to get the PowerShell processes on the computer, and it uses a pipeline operator (|) to send the processes to the Debug-Process cmdlet. To specify a particular PowerShell process, use the ID parameter of Get-Process.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>$pid | debug-process
This command attaches a debugger to the current PowerShell processes on the computer. It uses the $pid automatic variable, which contains the process ID of the current PowerShell process. Then, it uses a pipeline operator (|) to send the process ID to the Debug-Process cmdlet. For more information about the $pid automatic variable, see about_Automatic_Variables.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>get-process -computername Server01, Server02 -name MyApp | debug-process
This command attaches a debugger to the MyApp processes on the Server01 and Server02 computers. It uses the Get-Process cmdlet to get the MyApp processes on the Server01 and Server02 computers. It uses a pipeline operator to send the processes to the Debug-Process cmdlet, which attaches the debuggers.
-------------------------- EXAMPLE 8 --------------------------
PS C:\>$p = get-process powershell
PS C:\>debug-process -inputobject $p
This command attaches a debugger to the PowerShell processes on the local computer. The first command uses the Get-Process cmdlet to get the PowerShell processes on the computer. It saves the resulting process object in the $p variable. The second command uses the InputObject parameter of Debug-Process to submit the process object in the $p variable to Debug-Process.
###RELATED LINKS Online Version: Debug-Process Get-Process Start-Process Stop-Process Wait-Process ##Disable-ComputerRestore
###SYNOPSIS Disables the System Restore feature on the specified file system drive.
###SYNTAX TODO
###DESCRIPTION The Disable-ComputerRestore cmdlet turns off the System Restore feature on one or more file system drives. As a result, attempts to restore the computer do not affect the specified drive. To disable System Restore on any drive, it must be disabled on the system drive, either first or concurrently. To re-enable System Restore, use the Enable-ComputerRestore cmdlet. To find the state of System Restore for each drive, use Rstrui.exe. System restore points and the ComputerRestore cmdlets are supported only on client operating systems, such as Windows 7, Windows Vista, and Windows XP.
###PARAMETERS
####Drive <String[]>
Specifies the file system drives. Enter one or more file system drive letters, each followed by a colon and a backslash and enclosed in quotation marks, such as "C:" or "D:". This parameter is required. You cannot use this cmdlet to disable System Restore on a remote network drive, even if the drive is mapped to the local computer, and you cannot disable System Restore on drives that are not eligible for System Restore, such as external drives. To disable System Restore on any drive, System Restore must be disabled on the system drive, either before or concurrently.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None To run a Disable-ComputerRestore command on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. To find the file system drives that are eligible for system restore, in System in Control Panel, see the System Protection tab. To open this tab in Windows PowerShell, type "SystemPropertiesProtection". This cmdlet uses the Windows Management Instrumentation (WMI) SystemRestore class.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>disable-computerrestore -drive "C:\"
This command disables System Restore on the C: drive.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>disable-computerrestore "C:\", "D:\"
This command disables System Restore on the C: and D: drives. The command uses the Drive parameter, but it the omits the optional parameter name.
###RELATED LINKS Online Version: Checkpoint-Computer Enable-ComputerRestore Get-ComputerRestorePoint Restart-Computer Restore-Computer ##Enable-ComputerRestore
###SYNOPSIS Enables the System Restore feature on the specified file system drive.
###SYNTAX TODO
###DESCRIPTION The Enable-ComputerRestore cmdlet turns on the System Restore feature on one or more file system drives. As a result, you can use tools, such as the Restore-Computer cmdlet, to restore the computer to a previous state. By default, System Restore is enabled on all eligible drives, but you can disable it, such as by using the Disable-ComputerRestore cmdlet. To enable (or re-enable) System Restore on any drive, it must be enabled on the system drive, either first or concurrently. To find the state of System Restore for each drive, use Rstrui.exe. System restore points and the ComputerRestore cmdlets are supported only on client operating systems, such as Windows 7, Windows Vista, and Windows XP.
###PARAMETERS
####Drive <String[]>
Specifies the file system drives. Enter one or more file system drive letters, each followed by a colon and a backslash and enclosed in quotation marks, such as "C:" or "D:". This parameter is required. You cannot use this cmdlet to enable System Restore on a remote network drive, even if the drive is mapped to the local computer, and you cannot enable System Restore on drives that are not eligible for System Restore, such as external drives. To enable System Restore on any drive, System Restore must be enabled on the system drive, either before or concurrently.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe objects to this cmdlet.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None To run an Enable-ComputerRestore command on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. To find the file system drives that are eligible for system restore, in System in Control Panel, see the System Protection tab. To open this tab in Windows PowerShell, type "SystemPropertiesProtection". This cmdlet uses the Windows Management Instrumentation (WMI) SystemRestore class.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>enable-computerrestore -drive "C:\"
This command enables System Restore on the C: drive of the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>enable-computerrestore -drive "C:\", "D:\"
This command enables System Restore on the C: and D: drives of the local computer.
###RELATED LINKS Online Version: Checkpoint-Computer Disable-ComputerRestore Get-ComputerRestorePoint Restart-Computer Restore-Computer ##Get-ChildItem
###SYNOPSIS Gets the items and child items in one or more specified locations.
###SYNTAX TODO
###DESCRIPTION The Get-ChildItem cmdlet gets the items in one or more specified locations. If the item is a container, it gets the items inside the container, known as child items. You can use the Recurse parameter to get items in all child containers. A location can be a file system location, such as a directory, or a location exposed by a different Windows PowerShell provider, such as a registry hive or a certificate store.
###PARAMETERS
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to get items that cannot otherwise not be accessed by the user, such as hidden or system files. Implementation varies among providers. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). Even when using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Gets only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. The Include parameter is effective only when the command includes the Recurse parameter or the path leads to the contents of a directory, such as C:\Windows*, where the wildcard character specifies the contents of the C:\Windows directory.
####LiteralPath <String[]>
Specifies a path to one or more locations. Unlike the Path parameter, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name [<SwitchParameter>]
Gets only the names of the items in the locations. If you pipe the output of this command to another command, only the item names are sent.
####Path [<String[]>]
Specifies a path to one or more locations. Wildcards are permitted. The default location is the current directory (.).
####Recurse [<SwitchParameter>]
Gets the items in the specified locations and in all child items of the locations. In Windows PowerShell 2.0 and earlier versions of Windows PowerShell, the Recurse parameter works only when the value of the Path parameter is a container that has child items, such as C:\Windows or C:\Windows*, and not when it is an item does not have child items, such as C:\Windows*.exe.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Get-ChildItem.
###OUTPUTS ####System.Object System.String The type of object that Get-ChildItem returns is determined by the objects in the provider drive path. If you use the Name parameter, Get-ChildItem returns the object names as strings.
###NOTES ####System.Object System.String You can also refer to Get-ChildItem by its built-in aliases, "ls", "dir", and "gci". For more information, see about_Aliases. Get-ChildItem does not get hidden items by default. To get hidden items, use the Force parameter. The Get-ChildItem cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250).
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-ChildItem
This command gets the child items in the current location. If the location is a file system directory, it gets the files and sub-directories in the current directory. If the item does not have child items, this command returns to the command prompt without displaying anything. The default display lists the mode (attributes), last write time, file size (length), and the name of the file. The valid values for mode are d (directory), a (archive), r (read-only), h (hidden), and s (system).
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-ChildItem –Path *.txt -Recurse -Force
This command gets all of the .txt files in the current directory and its subdirectories. The Recurse parameter directs Windows PowerShell to get objects recursively, and it indicates that the subject of the command is the specified directory and its contents. The Force parameter adds hidden files to the display. To use the Recurse parameter on Windows PowerShell 2.0 and earlier versions of Windows PowerShell, the value use the Path parameter must be a container. Use the Include parameter to specify the .txt file type. For example, Get-ChildItem –Path .* -Include *.txt -Recurse -------------------------- EXAMPLE 3 --------------------------
PS C:\>Get-ChildItem –Path C:\Windows\Logs\* -Include *.txt -Exclude A*
This command lists the .txt files in the Logs subdirectory, except for those whose names start with the letter A. It uses the wildcard character (*) to indicate the contents of the Logs subdirectory, not the directory container. Because the command does not include the Recurse parameter, Get-ChildItem does not include the content of directory automatically; you need to specify it.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>Get-ChildItem –Path HKLM:\Software
This command gets all of the registry keys in the HKEY_LOCAL_MACHINE\SOFTWARE key in the registry of the local computer.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>Get-ChildItem -Name
This command gets only the names of items in the current directory.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>Import-Module Microsoft.PowerShell.Security
PS C:\>Get-ChildItem –Path Cert:\* -Recurse -CodeSigningCert
This command gets all of the certificates in the Windows PowerShell Cert: drive that have code-signing authority. The first command imports the Microsoft.PowerShell.Security module into the session. This module includes the Certificate provider that creates the Cert: drive. The second command uses the Get-ChildItem cmdlet. The value of the Path parameter is the Cert: drive. The Recurse parameter requests a recursive search. The CodeSigningCertificate parameter is a dynamic parameter that the Certificate provider adds to the Get-ChildItem cmdlet. This parameter gets only certificates that have code-signing authority. For more information about the Certificate provider and the Cert: drive, go to http://go.microsoft.com/fwlink/?LinkID=113433 or use the Update-Help cmdlet to download the help files for the Microsoft.PowerShell.Security module and then type "Get-Help Certificate". -------------------------- EXAMPLE 7 --------------------------
PS C:\>Get-ChildItem –Path C:\Windows –Include *mouse* -Exclude *.png
This command gets all of the items in the C:\Windows directory and its subdirectories that have "mouse" in the file name, except for those with a .png file name extension.
###RELATED LINKS Online Version: Get-Item Get-Location Get-Process about_Providers ##Get-ComputerRestorePoint
###SYNOPSIS Gets the restore points on the local computer.
###SYNTAX TODO
###DESCRIPTION The Get-ComputerRestorePoint cmdlet gets the restore points on the local computer. This cmdlet can also display the status of the most recent attempt to restore the computer. You can use the information returned by Get-ComputerRestorePoint to select a restore point, and you can use the sequence number to identify a restore point for the Restore-Computer cmdlet. System restore points and the Get-ComputerRestorePoint cmdlet are supported only on client operating systems, such as Windows 7, Windows Vista, and Windows XP.
###PARAMETERS
####LastStatus <SwitchParameter>
Gets the status of the most recent system restore operation.
####RestorePoint [<Int32[]>]
Gets the restore points with the specified sequence numbers. Enter the sequence numbers of one or more restore points. By default, Get-ComputerRestorePoint gets all restore points on the local computer.
###INPUTS ####None You cannot pipe objects to this cmdlet.
###OUTPUTS ####System.Management.ManagementObject#root\default\SystemRestore or String. Get-ComputerRestore returns a SystemRestore object, which is an instance of the WMI SystemRestore class. When you use the LastStatus parameter, this cmdlet returns a string.
###NOTES ####System.Management.ManagementObject#root\default\SystemRestore or String. To run a Get-ComputerRestorePoint command on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. This cmdlet uses the Windows Management Instrumentation (WMI) SystemRestore class.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-computerrestorepoint
This command gets all of the restore points on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-computerrestorepoint -restorepoint 232, 240, 245
This command gets the restore points with sequence numbers 232, 240, and 245.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-computerrestorepoint -laststatus
The last restore failed.
This command displays the status of the most recent system restore operation on the local computer.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-computerrestorepoint | format-table SequenceNumber, @{Label="Date"; Expression={$_.ConvertToDateTime($_.CreationTime)}}, Description -auto
SequenceNumber Date Description
-------------- ---- -----------
253 8/5/2008 3:19:20 PM Windows Update
254 8/6/2008 1:53:24 AM Windows Update
255 8/7/2008 12:00:04 AM Scheduled Checkpoint
...
This command displays the restore points in a table for easy reading. The Format-Table command includes a calculated property that uses the ConvertToDateTime method to convert the value of the CreationTime property from WMI format to a DateTime object.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>((get-computerrestorepoint)[-1]).sequencenumber
This command gets the sequence number of the most recently created restore point on the computer. The command uses the -1 index to get the last item in the array that Get-ComputerRestorePoint returns.
###RELATED LINKS Online Version: Checkpoint-Computer Disable-ComputerRestore Enable-ComputerRestore Restart-Computer Restore-Computer ##Get-Content
###SYNOPSIS Gets the content of the item at the specified location.
###SYNTAX TODO
###DESCRIPTION The Get-Content cmdlet gets the content of the item at the location specified by the path, such as the text in a file. It reads the content one line at a time and returns a collection of objects , each of which represents a line of content. Beginning in Windows PowerShell 3.0, Get-Content can also get a specified number of lines from the beginning or end of an item.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers that are installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when getting the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.
####Include [<String[]>]
Gets only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to an item. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the path to an item. Get-Content gets the content of the item. Wildcards are permitted. The parameter name ("Path" or "FilePath") is optional.
####ReadCount [<Int64>]
Specifies how many lines of content are sent through the pipeline at a time. The default value is 1. A value of 0 (zero) sends all of the content at one time. This parameter does not change the content displayed, but it does affect the time it takes to display the content. As the value of ReadCount increases, the time it takes to return the first line increases, but the total time for the operation decreases. This can make a perceptible difference in very large items.
####TotalCount [<Int64>]
Gets the specified number of lines from the beginning of a file or other item. The default is -1 (all lines). You can use the "TotalCount" parameter name or its aliases, "First" or "Head".
####Tail [<Int32>]
Gets the specified number of lines from the end of a file or other item. This parameter is introduced in Windows PowerShell 3.0. You can use the "Tail" parameter name or its alias, "Last".
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe input to Get-Content.
###OUTPUTS ####System.Byte, System.String Get-Content returns strings or bytes. The output type depends upon the content that it gets.
###NOTES ####System.Byte, System.String The Get-Content cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PsProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250).
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-Content -Path C:\Chapters\Chapter1.txt
This command gets the content of the Chapter1.txt file. It uses the Path parameter to specify the name of the item. Get-Content actually passes the content down the pipeline, but because there are no other pipeline elements, the content is formatted by default and displayed at the command line. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-Content c:\Logs\Log060912.txt -TotalCount 50 | Set-Content Sample.txt
This command gets the first 50 lines of the Log060912.txt file and stores them in the Sample.txt file. The command uses the Get-Content cmdlet to get the text in the file. (The name of Path parameter, which is optional, is omitted.) The TotalCount parameter limits the content retrieved to the first 50 lines. The pipeline operator (|) sends the result to the Set-Content cmdlet, which places it in the Sample.txt file. -------------------------- EXAMPLE 3 --------------------------
PS C:\>(Get-Content Cmdlets.txt -TotalCount 5)[-1]
This command gets the fifth line of the Cmdlets.txt text file. It uses the TotalCount parameter to get the first five lines and then uses array notation to get the last line (indicated by "-1") of the resulting set. -------------------------- EXAMPLE 4 --------------------------
PS C:\>dir .\*.txt | ForEach {Get-Content $_ -Head 1; Get-Content $_ -Tail 1}
This command gets the first and last lines of each text file in the current directory. The command uses the Tail parameter and the Head alias of the TotalCount parameter
###RELATED LINKS Online Version: Add-Content Clear-Content Set-Content about_Providers ##Get-ControlPanelItem
###SYNOPSIS Gets control panel items.
###SYNTAX TODO
###DESCRIPTION The Get-ControlPanelItem cmdlet gets control panel items on the local computer. You can use it to find control panel items by name, category, or description, even on systems that do not have a user interface. Get-ControlPanelItem gets only the control panel items that can be opened on the system. On computers that do not have Control Panel or File Explorer, Get-ControlPanelItem gets only control panel items that can open without these components. This cmdlet is introduced in Windows PowerShell 3.0. It works only on Windows 8 and Windows Server 2012.
###PARAMETERS
####CanonicalName <String[]>
Gets control panel items with the specified canonical names or name patterns. Wildcards are permitted. If you enter multiple names, Get-ControlPanelItem gets control panel items that match any of the names, as though the items in the name list were separated by an "or" operator. By default, Get-ControlPanelItem gets all control panel items in the system.
####Category [<String[]>]
Gets control panel items in the specified categories. Enter a category name or name pattern. Wildcards are permitted. If you enter multiple names, Get-ControlPanelItem gets control panel items that match any of the names, as though the items in the name list were separated by an "or" operator. By default, Get-ControlPanelItem gets all control panel items in the system.
####Name [<String[]>]
Gets control panel items with the specified names or name patterns. Wildcards are permitted. You can also pipe a name or name pattern to the Get-ControlPanelItem cmdlet.
###INPUTS ####System.String You can pipe a name or name pattern to the Get-ControlPanelItem cmdlet.
###OUTPUTS ####Microsoft.PowerShell.Commands.ControlPanelItem
###NOTES ####Microsoft.PowerShell.Commands.ControlPanelItem
###EXAMPLES Example 1: Get all control panel items
PS C:\>Get-ControlPanelItem
Name CanonicalName Category Description
---- ------------- -------- -----------
Action Center Microsoft.ActionCenter {System and Security} Review recent messages and...
Administrative Tools Microsoft.AdministrativeTools {System and Security} Configure administrative s...
AutoPlay Microsoft.AutoPlay {Hardware} Change default settings fo...
BitLocker Drive Encryption Microsoft.BitLockerDriveEn... {System and Security} Protect your computer usin...
Color Management Microsoft.ColorManagement {All Control Panel Items} Change advanced color mana...
Credential Manager Microsoft.CredentialManager {User Accounts} Manage your Windows Creden...
Date and Time Microsoft.DateAndTime {Clock, Language, and Region} Set the date, time, and ti...
This command gets all control panel items on the local computer. Example 2: Get control panel items by name
PS C:\>Get-ControlPanelItem –Name *program*, *app*
This command gets control panel items that have "program" or "app" in their names. Example 3: Get control panel items by category
PS C:\>Get-ControlPanelItem –Category *security*
This command gets all control panel items in categories that have "Security" in their names. Example 4: Open a control panel item
PS C:\>Get-ControlPanelItem –Name "Windows Firewall" | Show-ControlPanelItem
This command opens the Windows Firewall control panel item on the local computer. It uses the Get-ControlPanelItem cmdlet to get the control panel item and the Show-ControlPanelItem cmdlet to open it. Example 5: Get control panel items on a remote computer
PS C:\>Invoke-Command –ComputerName Server01 {Get-ControlPanelItem –Name "BitLocker*" }
This command gets the BitLocker Drive Encryption control panel item on the Server01 remote computer. It uses the Invoke-Command cmdlet to run the Get-ControlPanelItem cmdlet remotely. Example 6: Search the descriptions of control panel items
PS C:\>Get-ControlPanelItem | Where-Object {$_.Description -like "*device*"}
Name CanonicalName Category Description
---- ------------- -------- -----------
AutoPlay Microsoft.AutoPlay {Hardware} Change default settings fo...
Devices and Printers Microsoft.DevicesAndPrinters {Hardware} View and manage devices, p...
Sound Microsoft.Sound {Hardware} Configure your audio devic...
This command searches the Description property of the control panel item objects and gets only those that contain "device". The command uses the Get-ControlPanelItem cmdlet to get all control panel items and the Where-Object cmdlet to filter the items by the value of the Description property.
###RELATED LINKS Online Version: Show-ControlPanelItem ##Get-EventLog
###SYNOPSIS Gets the events in an event log, or a list of the event logs, on the local or remote computers.
###SYNTAX TODO
###DESCRIPTION The Get-EventLog cmdlet gets events and event logs on the local and remote computers. Use the parameters of Get-EventLog to search for events by using their property values. Get-EventLog gets only the events that match all of the specified property values. The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.
###PARAMETERS
####After [<DateTime>]
Gets only the events that occur after the specified date and time. Enter a DateTime object, such as the one returned by the Get-Date cmdlet.
####AsBaseObject [<SwitchParameter>]
Returns a standard System.Diagnostics.EventLogEntry object for each event. Without this parameter, Get-EventLog returns an extended PSObject object with additional EventLogName, Source, and InstanceId properties. To see the effect of this parameter, pipe the events to the Get-Member cmdlet and examine the TypeName value in the result.
####AsString [<SwitchParameter>]
Returns the output as strings, instead of objects.
####Before [<DateTime>]
Gets only the events that occur before the specified date and time. Enter a DateTime object, such as the one returned by the Get-Date cmdlet.
####ComputerName [<String[]>]
Specifies a remote computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-EventLog even if your computer is not configured to run remote commands.
####EntryType [<String[]>]
Gets only events with the specified entry type. Valid values are Error, Information, FailureAudit, SuccessAudit, and Warning. The default is all events.
####Index [<Int32[]>]
Gets only events with the specified index values.
####InstanceId [<Int64[]>]
Gets only events with the specified instance IDs.
####List [<SwitchParameter>]
Gets a list of event logs on the computer.
####LogName <String>
Specifies the event log. Enter the log name (the value of the Log property; not the LogDisplayName) of one event log. Wildcard characters are not permitted. This parameter is required.
####Message [<String>]
Gets events that have the specified string in their messages. You can use this property to search for messages that contain certain words or phrases. Wildcards are permitted.
####Newest [<Int32>]
Specifies the maximum number of events retrieved. Get-EventLog gets the specified number of events, beginning with the newest event in the log.
####Source [<String[]>]
Gets events that were written to the log by the specified sources. Wildcards are permitted.
####UserName [<String[]>]
Gets only the events that are associated with the specified user names. Enter names or name patterns, such as User01, User*, or Domain01\User*. Wildcards are permitted.
###INPUTS ####None. You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Diagnostics.EventLogEntry. System.Diagnostics.EventLog. System.String If the LogName parameter is specified, the output is a collection of EventLogEntry objects (System.Diagnostics.EventLogEntry). If only the List parameter is specified, the output is a collection of EventLog objects (System.Diagnostics.EventLog). If both the List and AsString parameters are specified, the output is a collection of Strings (System.String).
###NOTES ####System.Diagnostics.EventLogEntry. System.Diagnostics.EventLog. System.String The Get-EventLog and Get-WinEvent cmdlets are not supported in Windows Preinstallation Environment (Windows PE).
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-eventlog -list
This command gets the event logs on the computer. -------------------------- EXAMPLE 2 --------------------------
PS C:\>get-eventlog -newest 5 -logname application
This command gets the five most recent entries from the Application event log. -------------------------- EXAMPLE 3 --------------------------
PS C:\>$events = get-eventlog -logname system -newest 1000
PS C:\>$events | group-object -property source -noelement | sort-object -property count –descending
Count Name
----- ----
75 Service Control Manager
12 Print
6 UmrdpService
2 DnsApi
2 DCOM
1 Dhcp
1 TermDD
1 volsnap
This example shows how to find all of the sources that are represented in the 1000 most recent entries in the System event log. The first command gets the 1,000 most recent entries from the System event log and stores them in the $events variable. The second command uses a pipeline operator (|) to send the events in $events to the Group-Object cmdlet, which groups the entries by the value of the Source property. The command uses a second pipeline operator to send the grouped events to the Sort-Object cmdlet, which sorts them in descending order, so the most frequently appearing source is listed first. Source is just one property of event log entries. To see all of the properties of an event log entry, pipe the event log entries to the Get-Member cmdlet. -------------------------- EXAMPLE 4 --------------------------
PS C:\>get-eventlog -logname System -EntryType Error
This command gets only error events from the System event log. -------------------------- EXAMPLE 5 --------------------------
PS C:\>get-eventlog -logname System -instanceID 3221235481 -Source "DCOM"
This command gets events from the System log that have an InstanceID of 3221235481 and a Source value of "DCOM." -------------------------- EXAMPLE 6 --------------------------
PS C:\>get-eventlog -logname "Windows PowerShell" -computername localhost, Server01, Server02
This command gets the events from the "Windows PowerShell" event log on three computers, Server01, Server02, and the local computer, known as "localhost". -------------------------- EXAMPLE 7 --------------------------
PS C:\>get-eventlog -logname "Windows PowerShell" -message "*failed*"
This command gets all the events in the Windows PowerShell event log that have a message value that includes the word "failed". -------------------------- EXAMPLE 8 --------------------------
PS C:\>$a = get-eventlog -log System -newest 1
PS C:\>$a | format-list -property *
EventID : 7036
MachineName : Server01
Data : {}
Index : 10238
Category : (0)
CategoryNumber : 0
EntryType : Information
Message : The description for Event ID
Source : Service Control Manager
ReplacementStrings : {WinHTTP Web Proxy Auto-Disco
InstanceId : 1073748860
TimeGenerated : 4/11/2008 9:56:05 PM
TimeWritten : 4/11/2008 9:56:05 PM
UserName :
Site :
Container :
This example shows how to display the property values of an event in a list. The first command gets the newest event from the System event log and saves it in the $a variable. The second command uses a pipeline operator (|) to send the event in $a to the Format-List command, which displays all (*) of the event properties. -------------------------- EXAMPLE 9 --------------------------
PS C:\>get-eventlog -log application -source outlook | where {$_.eventID -eq 34}
This command gets events in the Application event log where the source is Outlook and the event ID is 34. Even though Get-EventLog does not have an EventID parameter, you can use the Where-Object cmdlet to select events based on the value of any event property. -------------------------- EXAMPLE 10 --------------------------
PS C:\>get-eventlog -log system -username NT* | group-object -property username -noelement | format-table Count, Name -auto
Count Name
----- ----
6031 NT AUTHORITY\SYSTEM
42 NT AUTHORITY\LOCAL SERVICE
4 NT AUTHORITY\NETWORK SERVICE
This command returns the events in the system log grouped by the value of their UserName property. The Get-EventLog command uses the UserName parameter to get only events in which the user name begins with "NT*". -------------------------- EXAMPLE 11 --------------------------
PS C:\>$May31 = get-date 5/31/08
PS C:\>$July1 = get-date 7/01/08
PS C:\>get-eventlog -log "Windows PowerShell" -entrytype Error -after $may31 -before $july1
This command gets all of the errors in the Windows PowerShell event log that occurred in June 2008.
###RELATED LINKS Online Version: Clear-EventLog Limit-EventLog New-EventLog Remove-EventLog Show-EventLog Write-EventLog ##Get-HotFix
###SYNOPSIS Gets the hotfixes that have been applied to the local and remote computers.
###SYNTAX TODO
###DESCRIPTION The Get-Hotfix cmdlet gets hotfixes (also called updates) that have been installed on either the local computer (or on specified remote computers) by Windows Update, Microsoft Update, or Windows Server Update Services; the cmdlet also gets hotfixes or updates that have been installed manually by users.
###PARAMETERS
####ComputerName [<String[]>]
Specifies a remote computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-Hotfix even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
####Description [<String[]>]
Gets only hotfixes with the specified descriptions. Wildcards are permitted. The default is all hotfixes on the computer.
####Id [<String[]>]
Gets only hotfixes with the specified hotfix IDs. The default is all hotfixes on the computer.
###INPUTS ####None You cannot pipe input to Get-HotFix.
###OUTPUTS ####System.Management.ManagementObject#root\CIMV2\Win32_QuickFixEngineering Get-Hotfix returns objects that represent the hotfixes on the computer.
###NOTES ####System.Management.ManagementObject#root\CIMV2\Win32_QuickFixEngineering This cmdlet uses the Win32_QuickFixEngineering WMI class, which represents small system-wide updates of the operating system. Starting with Windows Vista, this class returns only the updates supplied by Microsoft Windows Installer (MSI), Windows Update, Microsoft Update, or Windows Server Update Services. It does not include updates that are supplied by Component Based Servicing (CBS), or other non-hotfix programs or apps. For more information, see the Win32_QuickFixEngineering class topic in the Microsoft .NET Framework SDK at http://go.microsoft.com/fwlink/?LinkID=145071. The output of this cmdlet might be different on different operating systems.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-hotfix
This command gets all hotfixes on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-hotfix -description Security* -computername Server01, Server02 -cred Server01\admin01
This command gets all hotfixes on the Server01 and Server02 computers that have a description that begins with "Security".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$a = get-content servers.txt
PS C:\>$a | foreach { if (!(get-hotfix -id KB957095 -computername $_)) { add-content $_ -path Missing-kb953631.txt }}
The commands in this example create a text file listing the names of computers that are missing a security update. The commands use the Get-Hotfix cmdlet to get the KB957095 security update on all of the computers whose names are listed in the Servers.txt file. If a computer does not have the update, the Add-Content cmdlet writes the computer name in the Missing-KB953631.txt file.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>(get-hotfix | sort installedon)[-1]
This command gets the most recent hotfix on the computer. It gets the hotfixes, sorts them by the value of the InstalledOn property, and then it uses array notation to select the last item in the array.
###RELATED LINKS Online Version: Get-ComputerRestorePoint ##Get-Item
###SYNOPSIS Gets the item at the specified location.
###SYNTAX TODO
###DESCRIPTION The Get-Item cmdlet gets the item at the specified location. It does not get the contents of the item at the location unless you use a wildcard character (*) to request all the contents of the item. The Get-Item cmdlet is used by Windows PowerShell providers to enable you to navigate through different types of data stores.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user-name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. The Exclude parameter is effective only when the command includes the contents of an item, such as C:\Windows*, where the wildcard character specifies the contents of the C:\Windows directory.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to get items that cannot otherwise be accessed, such as hidden items. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Retrieves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. The Include parameter is effective only when the command includes the contents of an item, such as C:\Windows*, where the wildcard character specifies the contents of the C:\Windows directory.
####LiteralPath <String[]>
Specifies a path to the item. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the path to an item. Get-Item gets the item at the specified location. Wildcards are permitted. This parameter is required, but the parameter name ("Path") is optional. Use a dot (.) to specify the current location. Use the wildcard character (*) to specify all the items in the current location.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Get-Item.
###OUTPUTS ####System.Object Get-Item returns the objects that it gets. The type is determined by the type of objects in the path.
###NOTES ####System.Object You can also refer to Get-Item by its built-in alias, "gi". For more information, see about_Aliases. Get-Item does not have a Recurse parameter, because it gets only an item, not its contents. To get the contents of an item recursively, use Get-ChildItem. To navigate through the registry, use Get-Item to get registry keys and Get-ItemProperty to get registry values and data. The registry values are considered to be properties of the registry key. The Get-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-item .
Directory: C:\
Mode LastWriteTime Length Name
---- ------------- ------ ----
d---- 7/26/2006 10:01 AM ps-test
This command gets the current directory. The dot (.) represents the item at the current location (not its contents).
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-item *
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
d---- 7/26/2006 9:29 AM Logs
d---- 7/26/2006 9:26 AM Recs
-a--- 7/26/2006 9:28 AM 80 date.csv
-a--- 7/26/2006 10:01 AM 30 filenoext
-a--- 7/26/2006 9:30 AM 11472 process.doc
-a--- 7/14/2006 10:47 AM 30 test.txt
This command gets all the items in the current directory. The wildcard character (*) represents all the contents of the current item.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-item C:\
This command gets the current directory of the C: drive. The object that is retrieved represents only the directory, not its contents.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-item C:\*
This command gets the items in the C: drive. The wildcard character () represents all the items in the container, not just the container. In Windows PowerShell, use a single asterisk () to get contents, instead of the traditional ".". The format is interpreted literally, so "." would not retrieve directories or file names without a dot.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>(get-item C:\Windows).LastAccessTime
This command gets the LastAccessTime property of the C:\Windows directory. LastAccessTime is just one property of file system directories. To see all of the properties of a directory, type "(Get-Item ) | Get-Member".
-------------------------- EXAMPLE 6 --------------------------
PS C:\>get-item hklm:\software\microsoft\powershell\1\shellids\microsoft.powershell\*
This command shows the contents of the Microsoft.PowerShell registry key. You can use Get-Item with the Windows PowerShell Registry provider to get registry keys and subkeys, but you must use Get-ItemProperty to get the registry values and data.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>get-item c:\Windows\*.* -exclude w*
This command gets items in the Windows directory with names that include a dot (.), but do not begin with w*. This command works only when the path includes a wildcard character (*) to specify the contents of the item.
###RELATED LINKS Online Version: Clear-Item Copy-Item Invoke-Item Move-Item New-Item Remove-Item Rename-Item Set-Item about_Providers ##Get-ItemProperty
###SYNOPSIS Gets the properties of a specified item.
###SYNTAX TODO
###DESCRIPTION The Get-ItemProperty cmdlet gets the properties of the specified items. For example, you can use Get-ItemProperty to get the value of the LastAccessTime property of a file object. You can also use Get-ItemProperty to view registry entries and their values.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Include [<String[]>]
Includes the specified items.
####LiteralPath <String[]>
Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name [<String[]>]
Specifies the name of the property or properties to retrieve.
####Path <String[]>
Specifies the path to the item or items.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Get-ItemProperty.
###OUTPUTS ####System.Boolean, System.String, System.DateTime Get-ItemProperty returns an object for each item property that it gets. The object type depends on the object that is retrieved. For example, in a file system drive, it might return a file or folder.
###NOTES ####System.Boolean, System.String, System.DateTime The Get-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-ItemProperty C:\Windows
This command gets information about the C:\Windows directory.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-ItemProperty C:\Test\Weather.xls | Format-List
This command gets the properties of the C:\Test\Weather.xls file. The result is piped to the Format-List cmdlet to display the output as a list.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
This command displays the value name and data of each of the registry entries contained in the CurrentVersion registry subkey. Note that the command requires that there is a Windows PowerShell drive named HKLM: that is mapped to the HKEY_LOCAL_MACHINE hive of the registry. A drive with that name and mapping is available in Windows PowerShell by default. Alternatively, the path to this registry subkey can be specified by using the following alternative path that begins with the provider name followed by two colons: Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion -name "ProgramFilesDir"
This command gets the value name and data of the ProgramFilesDir registry entry in the CurrentVersion registry subkey. The command uses the Path parameter to specify the subkey and the Name parameter to specify the value name of the entry. The command uses a back tick or "grave accent" (`), the Windows PowerShell continuation character, to continue the command on the second line. -------------------------- EXAMPLE 5 --------------------------
PS C:\>Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine
ApplicationBase : C:\Windows\system32\WindowsPowerShell\v1.0\
ConsoleHostAssemblyName : Microsoft.PowerShell.ConsoleHost, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, ProcessorArchitecture=msil
PowerShellVersion : 2.0
RuntimeVersion : v2.0.50727
CTPVersion : 5
PSCompatibleVersion : 1.0,2.0
This command gets the value names and data of the registry entries in the PowerShellEngine registry key. The results are shown in the following sample output.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
Path ExecutionPolicy
---- ---------------
C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe RemoteSigned
PS C:\>Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell | Format-List -property *
PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\PowerShell\1\ShellIds\Micro
soft.PowerShell
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\PowerShell\1\ShellIds
PSChildName : Microsoft.PowerShell
PSDrive : HKLM
PSProvider : Microsoft.PowerShell.Core\Registry
Path : C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe
ExecutionPolicy : RemoteSigned
This example shows how to format the output of a Get-ItemProperty command in a list to make it easy to see the registry values and data and to make it easy to interpret the results. The first command uses the Get-ItemProperty cmdlet to get the registry entries in the Microsoft.PowerShell subkey. This subkey stores options for the default shell for Windows PowerShell. The results are shown in the following sample output. The output shows that there are two registry entries, Path and ExecutionPolicy. When a registry key contains fewer than five entries, by default it is displayed in a table, but it is often easier to view in a list. The second command uses the same Get-ItemProperty command. However, this time, the command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet. The Format-List command uses the Property parameter with a value of * (all) to display all of the properties of the objects in a list. The results are shown in the following sample output. The resulting display shows the Path and ExecutionPolicy registry entries, along with several less familiar properties of the registry key object. The other properties, prefixed with "PS", are properties of Windows PowerShell custom objects, such as the objects that represent the registry keys.
###RELATED LINKS Online Version: Clear-ItemProperty Copy-ItemProperty Move-ItemProperty New-ItemProperty Remove-ItemProperty Rename-ItemProperty Set-ItemProperty about_Providers ##Get-Location
###SYNOPSIS Gets information about the current working location or a location stack.
###SYNTAX TODO
###DESCRIPTION The Get-Location cmdlet gets an object that represents the current directory, much like the pwd (print working directory) command. When you move between Windows PowerShell drives, Windows PowerShell retains your location in each drive. You can use Get-Location to find your location in each drive. You can use Get-Location to get the current directory at run time and use it in functions and scripts, such as in a function that displays the current directory in the Windows PowerShell prompt. You can also use the Get-Location cmdlet to display the locations in a location stack. For more information, see the Notes and the descriptions of the Stack and StackName parameters.
###PARAMETERS
####PSDrive [<String[]>]
Gets the current location in the specified Windows PowerShell drive. For example, if you are in the Certificate: drive, you can use this parameter to find your current location in the C: drive.
####PSProvider [<String[]>]
Gets the current location in the drive supported by the specified Windows PowerShell provider. If the specified provider supports more than one drive, Get-Location returns the location on the most recently accessed drive. For example, if you are in the C: drive, you can use this parameter to find your current location in the drives of the Windows PowerShell Registry provider.
####Stack [<SwitchParameter>]
Displays the locations in the current location stack. To display the locations in a different location stack, use the StackName parameter. For information about location stacks, see the Notes.
####StackName [<String[]>]
Displays the locations in the specified named location stacks. Enter one or more location stack names. To display the locations in the current location stack, use the Stack parameter. To make a location stack the current location stack, use the Set-Location parameter. For information about location stacks, see the Notes. NOTE: Get-Location cannot display the locations in the unnamed default stack unless it is the current stack.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Management.Automation.PathInfo or System.Management.Automation.PathInfoStack If you use the Stack or StackName parameters, Get-Location returns a StackInfo object. Otherwise, it returns a PathInfo object.
###NOTES ####System.Management.Automation.PathInfo or System.Management.Automation.PathInfoStack The Get-Location cmdlet is designed to work with the data exposed by any provider. To list the providers in your session, type "Get-PSProvider". For more information, see about_Providers. The ways that the PSProvider, PSDrive, Stack, and StackName parameters interact depends on the provider. Some combinations will result in errors, such as specifying both a drive and a provider that does not expose that drive. If no parameters are specified, Get-Location returns the PathInfo object for the provider that contains the current working location. A "stack" is a last-in, first-out list in which only the most recently added item is accessible. You add items to a stack in the order that you use them, and then retrieve them for use in the reverse order. Windows PowerShell lets you store provider locations in location stacks. Windows PowerShell creates an unnamed default location stack and you can create multiple named location stacks. If you do not specify a stack name, Windows PowerShell uses the current location stack. By default, the unnamed default location is the current location stack, but you can use the Set-Location cmdlet to change the current location stack. To manage location stacks, use the Windows PowerShell Location cmdlets, as follows. -- To add a location to a location stack, use the Push-Location cmdlet. -- To get a location from a location stack, use the Pop-Location cmdlet. -- To display the locations in the current location stack, use the Stack parameter of the Get-Location cmdlet. To display the locations in a named location stack, use the StackName parameter of the Get-Location cmdlet. -- To create a new location stack, use the StackName parameter of the Push-Location cmdlet. If you specify a stack that does not exist, Push-Location creates the stack. -- To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. The unnamed default location stack is fully accessible only when it is the current location stack. If you make a named location stack the current location stack, you cannot no longer use Push-Location or Pop-Location cmdlets add or get items from the default stack or use Get-Location command to display the locations in the unnamed stack. To make the unnamed stack the current stack, use the StackName parameter of the Set-Location cmdlet with a value of $null or an empty string ("").
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-location
Path
----
C:\WINDOWS
This command displays your location in the current Windows PowerShell drive. For example, if you are in the Windows directory of the C: drive, it displays the path to that directory.
-------------------------- EXAMPLE 2 --------------------------
The first command uses the Set-Location cmdlet to set the current location to the Windows subdirectory of the C: drive.
PS C:\>set-location C:\Windows
The second command uses the Set-Location cmdlet to change the location to the HKLM:\Software\Microsoft registry key. When you change to a location in the HKLM: drive, Windows PowerShell retains your location in the C: drive.
PS C:\WINDOWS> set-location HKLM:\Software\Microsoft
PS HKLM:\Software\Microsoft>
The third command uses the Set-Location cmdlet to change the location to the "HKCU:\Control Panel\Input Method" registry key.
PS C:\>PS HKLM:\Software\Microsoft> set-location 'HKCU:\Control Panel\Input Method'
PS HKCU:\Control Panel\Input Method>
The fourth command uses the Get-Location cmdlet to find the current location on the C: drive. It uses the PSDrive parameter to specify the drive.
PS C:\>PS HKCU:\Control Panel\Input Method> get-location -psdrive c
Path
----
C:\WINDOWS
The fifth command uses the Set-Location cmdlet to return to the C: drive. Even though the command does not specify a subdirectory, Windows PowerShell returns you to the saved location.
PS C:\>PS HKCU:\Control Panel\Input Method> set-location C:
PS C:\WINDOWS>
The sixth command uses the Get-Location cmdlet to find the current location in the drives supported by the Windows PowerShell registry provider. Get-Location returns the location of the most recently accessed registry drive, HKCU.
PS C:\WINDOWS> get-location -psprovider registry
Path
----
HKCU:\Control Panel\Input Method
To see the current location in the HKLM: drive, you need to use the PSDrive parameter to specify the drive. The seventh command does just this:
PS C:\WINDOWS> get-location -psdrive HKLM
Path
----
HKLM:\Software\Microsoft
These commands demonstrate the use of Get-Location to display your current location in different Windows PowerShell drives. -------------------------- EXAMPLE 3 --------------------------
The first command sets the current location to the Windows directory on the C: drive.
PS C:\>set-location C:\Windows
The second command uses the Push-Location cmdlet to push the current location (C:\Windows) onto the current location stack and change to the System32 subdirectory. Because no stack is specified, the current location is pushed onto the current location stack. By default, the current location stack is the unnamed default location stack.
C:\WINDOWS>push-location System32
The third command uses the StackName parameter of the Push-Location cmdlet to push the current location (C:\Windows\System32) onto the Stack2 stack and to change the current location to the WindowsPowerShell subirectory. If the Stack2 stack does not exist, Push-Location creates it.
C:\Windows\System32>push-location WindowsPowerShell -StackName Stack2
The fourth command uses the Stack parameter of the Get-Location cmdlet to get the locations in the current location stack. By default, the current stack is the unnamed default location stack.
C:\WINDOWS\system32\WindowsPowerShell>get-location -stack
Path
----
C:\WINDOWS
The fifth command uses the StackName parameter of the Get-Location cmdlet to get the locations in the Stack2 stack.
C:\WINDOWS\system32\WindowsPowerShell>get-location -stackname Stack2
Path
----
C:\WINDOWS\system32
These commands show how to use the Stack and StackName parameters of Get-Location to list the locations in the current location stack and alternate location stacks. For more information about location stacks, see the Notes. -------------------------- EXAMPLE 4 --------------------------
PS C:\>function prompt { 'PowerShell: ' + (get-location) + '> '}
PowerShell: C:\WINDOWS>
This example shows how to customize the Windows PowerShell prompt. The function that defines the prompt includes a Get-Location command, which is run whenever the prompt appears in the console. The format of the default Windows PowerShell prompt is defined by a special function called "prompt". You can change the prompt in your console by creating a new function called "prompt". To see the current prompt function, type the following command: get-content function:prompt The command begins with the "function" keyword followed by the function name, "prompt". The function body appears within braces ( {} ). This command defines a new prompt that begins with the string "PowerShell: ". To append the current location, it uses a Get-Location command, which runs when the prompt function is called. The prompt ends with the string "> ".
###RELATED LINKS Online Version: Pop-Location Push-Location Set-Location about_Providers ##Get-Process
###SYNOPSIS Gets the processes that are running on the local computer or a remote computer.
###SYNTAX TODO
###DESCRIPTION The Get-Process cmdlet gets the processes on a local or remote computer. Without parameters, Get-Process gets all of the processes on the local computer. You can also specify a particular process by process name or process ID (PID) or pass a process object through the pipeline to Get-Process. By default, Get-Process returns a process object that has detailed information about the process and supports methods that let you start and stop the process. You can also use the parameters of Get-Process to get file version information for the program that runs in the process and to get the modules that the process loaded.
###PARAMETERS
####ComputerName [<String[]>]
Gets the processes running on the specified computers. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more computers. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-Process even if your computer is not configured to run remote commands.
####FileVersionInfo [<SwitchParameter>]
Gets the file version information for the program that runs in the process. On Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option to use this parameter on processes that you do not own. You cannot use the FileVersionInfo and ComputerName parameters of the Get-Process cmdlet in the same command. To get file version information for a process on a remote computer, use the Invoke-Command cmdlet. Using this parameter is equivalent to getting the MainModule.FileVersionInfo property of each process object. When you use this parameter, Get-Process returns a FileVersionInfo object (System.Diagnostics.FileVersionInfo), not a process object. So, you cannot pipe the output of the command to a cmdlet that expects a process object, such as Stop-Process.
####Id <Int32[]>
Specifies one or more processes by process ID (PID). To specify multiple IDs, use commas to separate the IDs. To find the PID of a process, type "get-process".
####IncludeUserName <SwitchParameter>
Specifies that the UserName value of the Process object is returned with results of the command.
####InputObject <Process[]>
Specifies one or more process objects. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Module [<SwitchParameter>]
Gets the modules that have been loaded by the processes. On Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option to use this parameter on processes that you do not own. You cannot use the Module and ComputerName parameters of the Get-Process cmdlet in the same command. To get the modules that have been loaded by a process on a remote computer, use the Invoke-Command cmdlet. This parameter is equivalent to getting the Modules property of each process object. When you use this parameter, Get-Process returns a ProcessModule object (System.Diagnostics.ProcessModule), not a process object. So, you cannot pipe the output of the command to a cmdlet that expects a process object, such as Stop-Process. When you use both the Module and FileVersionInfo parameters in the same command, Get-Process returns a FileVersionInfo object with information about the file version of all modules.
####Name [<String[]>]
Specifies one or more processes by process name. You can type multiple process names (separated by commas) and use wildcard characters. The parameter name ("Name") is optional.
###INPUTS ####System.Diagnostics.Process You can pipe a process object to Get-Process.
###OUTPUTS ####System.Diagnostics.Process, System.Diagnotics.FileVersionInfo, System.Diagnostics.ProcessModule By default, Get-Process returns a System.Diagnostics.Process object. If you use the FileVersionInfo parameter, it returns a System.Diagnotics.FileVersionInfo object. If you use the Module parameter (without the FileVersionInfo parameter), it returns a System.Diagnostics.ProcessModule object.
###NOTES ####System.Diagnostics.Process, System.Diagnotics.FileVersionInfo, System.Diagnostics.ProcessModule You can also refer to Get-Process by its built-in aliases, "ps" and "gps". For more information, see about_Aliases. On computers that are running a 64-bit version of Windows, the 64-bit version of Windows PowerShell gets only 64-bit process modules and the 32-bit version of Windows PowerShell gets only 32-bit process modules. You can use the properties and methods of the WMI Win32_Process object in Windows PowerShell. For information, see T:Microsoft.PowerShell.Commands.Get-WmiObject and the Windows Management Instrumentation (WMI) SDK. The default display of a process is a table that includes the following columns. For a description of all of the properties of process objects, see "Process Properties" on MSDN at http://go.microsoft.com/fwlink/?LinkId=204482. -- Handles: The number of handles that the process has opened. -- NPM(K): The amount of non-paged memory that the process is using, in kilobytes. -- PM(K): The amount of pageable memory that the process is using, in kilobytes. -- WS(K): The size of the working set of the process, in kilobytes. The working set consists of the pages of memory that were recently referenced by the process. -- VM(M): The amount of virtual memory that the process is using, in megabytes. Virtual memory includes storage in the paging files on disk. -- CPU(s): The amount of processor time that the process has used on all processors, in seconds. -- ID: The process ID (PID) of the process. -- ProcessName: The name of the process. For explanations of the concepts related to processes, see the Glossary in Help and Support Center and the Help for Task Manager. You can also use the built-in alternate views of the processes available with Format-Table, such as "StartTime" and "Priority", and you can design your own views. For more information, see T:Microsoft.PowerShell.Commands.Format-Table.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-Process
This command gets a list of all of the running processes running on the local computer. For a definition of each column, see the "Additional Notes" section of the Help topic for Get-Help.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-Process winword, explorer | format-list *
This command gets all available data about the Winword and Explorer processes on the computer. It uses the Name parameter to specify the processes, but it omits the optional parameter name. The pipeline operator (|) passes the data to the Format-List cmdlet, which displays all available properties (*) of the Winword and Explorer process objects. You can also identify the processes by their process IDs. For example, "get-process -id 664, 2060".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-process | where-object {$_.WorkingSet -gt 20000000}
This command gets all processes that have a working set greater than 20 MB. It uses the Get-Process cmdlet to get all running processes. The pipeline operator (|) passes the process objects to the Where-Object cmdlet, which selects only the object with a value greater than 20,000,000 bytes for the WorkingSet property. WorkingSet is one of many properties of process objects. To see all of the properties, type "Get-Process | Get-Member". By default, the values of all amount properties are in bytes, even though the default display lists them in kilobytes and megabytes.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>$a = get-process
PS C:\>get-process -inputobject $a | format-table -view priority
These commands list the processes on the computer in groups based on their priority class. The first command gets all the processes on the computer and then stores them in the $a variable. The second command uses the InputObject parameter to pass the process objects that are stored in the $a variable to the Get-Process cmdlet. The pipeline operator passes the objects to the Format-Table cmdlet, which formats the processes by using the Priority view. The Priority view, and other views, are defined in the PS1XML format files in the Windows PowerShell home directory ($pshome). -------------------------- EXAMPLE 5 --------------------------
PS C:\>get-process powershell -computername S1, localhost | ft @{Label="NPM(K)";Expression={[int]($_.NPM/1024)}}, @{Label="PM(K)";Expression={[int]($_.PM/1024)}},@{Label="WS(K)";Expression={[int]($_.WS/1024)}},@{Label="VM(M)";Expression={[int]($_.VM/1MB)}}, @{Label="CPU(s)";Expression={if ($_.CPU -ne $()) { $_.CPU.ToString("N")}}}, Id, MachineName, ProcessName -auto
NPM(K) PM(K) WS(K) VM(M) CPU(s) Id MachineName ProcessName
------ ----- ----- ----- ------ -- ----------- -----------
6 23500 31340 142 1980 S1 powershell
6 23500 31348 142 4016 S1 powershell
27 54572 54520 576 4428 localhost powershell
This example provides a Format-Table (alias = ft) command that adds the MachineName property to the standard Get-Process output display. -------------------------- EXAMPLE 6 --------------------------
PS C:\>get-process powershell -fileversioninfo
ProductVersion FileVersion FileName
-------------- ----------- --------
6.1.6713.1 6.1.6713.1 (f... C:\WINDOWS\system32\WindowsPowerShell\v1.0\powershell.exe
This command uses the FileVersionInfo parameter to get the version information for the PowerShell.exe file that is the main module for the PowerShell process. To run this command with processes that you do not own on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>get-process sql* -module
This command uses the Module parameter to get the modules that have been loaded by the process. This command gets the modules for the processes that have names that begin with "sql". To run this command on Windows Vista (and later versions of Windows) with processes that you do not own, you must start Windows PowerShell with the "Run as administrator" option.
-------------------------- EXAMPLE 8 --------------------------
PS C:\>$p = get-wmiobject win32_process -filter "name='powershell.exe'"
PS C:\>$p.getowner()
__GENUS : 2
__CLASS : __PARAMETERS
__SUPERCLASS :
__DYNASTY : __PARAMETERS
__RELPATH :
__PROPERTY_COUNT : 3
__DERIVATION : {}
__SERVER :
__NAMESPACE :
__PATH :
Domain : DOMAIN01
ReturnValue : 0
User : user01
This command shows how to find the owner of a process. Because the System.Diagnostics.Process object that Get-Process returns does not have a property or method that returns the process owner, the command uses the Get-WmiObject cmdlet to get a Win32_Process object that represents the same process. The first command uses Get-WmiObject to get the PowerShell process. It saves it in the $p variable. The second command uses the GetOwner method to get the owner of the process in $p. The command reveals that the owner is Domain01\user01.
-------------------------- EXAMPLE 9 --------------------------
PS C:\>get-process powershell
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
308 26 52308 61780 567 3.18 5632 powershell
377 26 62676 63384 575 3.88 5888 powershell
PS C:\>get-process -id $pid
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
396 26 56488 57236 575 3.90 5888 powershell
These commands show how to use the $pid automatic variable to identify the process that is hosting the current Windows PowerShell session. You can use this method to distinguish the host process from other Windows PowerShell processes that you might want to stop or close. The first command gets all of the Windows PowerShell processes in the current session. The second command gets the Windows PowerShell process that is hosting the current session. -------------------------- EXAMPLE 10 --------------------------
PS C:\>get-process | where {$_.mainWindowTitle} | format-table id, name, mainwindowtitle -autosize
This command gets all the processes that have a main window title, and it displays them in a table with the process ID and the process name. The mainWindowTitle property is just one of many useful properties of the System.Diagnostics.Process object that Get-Process returns. To view all of the properties, pipe the results of a Get-Process command to the T:Microsoft.PowerShell.Commands.Get-Member cmdlet (get-process | get-member).
###RELATED LINKS Online Version: Debug-Process Get-Process Start-Process Stop-Process Wait-Process ##Get-PSDrive
###SYNOPSIS Gets drives in the current session.
###SYNTAX TODO
###DESCRIPTION The Get-PSDrive cmdlet gets the drives in the current session. You can get a particular drive or all drives in the session. Get-PSDrive gets the following types of drives: -- Windows logical drives on the computer, including drives mapped to network shares. -- Drives exposed by Windows PowerShell providers (such as the Certificate:, Function:, and Alias: drives) and the HKLM: and HKCU: drives that are exposed by the Windows PowerShell Registry provider. -- Session-specified temporary drives and persistent mapped network drives that you create by using the New-PSDrive cmdlet. Beginning in Windows PowerShell 3.0, the Persist parameter of the New-PSDrive cmdlet can create mapped network drives that are saved on the local computer and are available in other sessions. For more information, see New-PSDrive. Also, beginning in Windows PowerShell 3.0, when an external drive is connected to the computer, Windows PowerShell automatically adds a PSDrive to the file system that represents the new drive. You do not need to restart Windows PowerShell. Similarly, when an external drive is disconnected from the computer, Windows PowerShell automatically deletes the PSDrive that represents the removed drive.
###PARAMETERS
####LiteralName <String[]>
Specifies the name of the drive. The value of LiteralName is used exactly as it is typed. No characters are interpreted as wildcards. If the name includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name [<String[]>]
Gets only the specified drives. Type the drive name or letter without a colon (:).
####PSProvider [<String[]>]
Gets only the drives supported by the specified Windows PowerShell provider. Type the name of a provider, such as FileSystem, Registry, or Certificate.
####Scope [<String>]
Gets only drives in the specified scope. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes (http://go.microsoft.com/fwlink/?LinkID=113260).
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter can only be used when a transaction is in progress. For more information, see about_Transactions.
###INPUTS ####None You cannot pipe objects to Get-PSDrive.
###OUTPUTS ####System.Management.Automation.PSDriveInfo Get-PSDrive returns objects that represent the drives in the session.
###NOTES ####System.Management.Automation.PSDriveInfo The Get-PSDrive cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). Mapped network drives that are created by using the Persist parameter of the New-PSDrive cmdlet are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credentials of another user are not visible in sessions that are started without explicit credentials or with the credentials of the current user.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-PSDrive
Name Provider Root
---- -------- ----
Alias Alias
C FileSystem C:\
cert Certificate \
D FileSystem D:\
Env Environment
Function Function
HKCU Registry HKEY_CURRENT_USER
HKLM Registry HKEY_LOCAL_MACHINE
Variable Variable
X FileSystem X:\
This command gets the drives in the current session. The output shows the hard drive (C:) and CD-ROM drive (D:) on the computer, the drives exposed by the Windows PowerShell providers (Alias:, Cert:, Env:, Function:, HKCU:, HKLM:, and Variable:), and a drive mapped to a network share (X:). -------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-PSDrive D
Name Provider Root
---- -------- ----
D FileSystem D:\
This command gets the D: drive on the computer. Note that the drive letter in the command is not followed by a colon. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Get-PSDrive -PSProvider FileSystem
Name Provider Root
---- -------- ----
C FileSystem C:\
D FileSystem D:\
X FileSystem X:\
Y FileSystem \\Server01\Public
Z FileSystem C:\Windows\System32
This command gets all of the drives that are supported by the Windows PowerShell FileSystem provider. This includes fixed drives, logical partitions, mapped network drives, and temporary drives that you create by using the New-PSDrive cmdlet. -------------------------- EXAMPLE 4 --------------------------
PS C:\>if (!(Get-PSDrive X)) {New-PSDrive -Name X -PSProvider Registry -Root HKLM:\Network}
else { Write-Host "The X: drive is already in use." }
This command checks to see whether the X drive is already in use as a Windows PowerShell drive name. If it is not, the command uses the New-PSDrive cmdlet to create a temporary drive that is mapped to the HKLM:\Network registry key. -------------------------- EXAMPLE 5 --------------------------
PS C:\>Get-PSDrive -PSProvider FileSystem
PS C:\>Get-PSDrive -provider FileSystem
Name Provider Root
---- -------- ----
C FileSystem C:\
D FileSystem D:\
X FileSystem X:\
Y FileSystem \\Server01\Public
Z FileSystem C:\Windows\System32
PS C:\>net use
New connections will be remembered.
Status Local Remote Network
-------------------------------------------------------------------------------
X: \\Server01\Public Microsoft Windows Network
PS C:\>[System.IO.DriveInfo]::getdrives()
Name : C:\
DriveType : Fixed
DriveFormat : NTFS
IsReady : True
AvailableFreeSpace : 39831498752
TotalFreeSpace : 39831498752
TotalSize : 79900368896
RootDirectory : C:\
VolumeLabel :
Name : D:\
DriveType : CDRom
DriveFormat :
IsReady : False
AvailableFreeSpace :
TotalFreeSpace :
TotalSize :
RootDirectory : D:\
VolumeLabel :
Name : X:\
DriveType : Network
DriveFormat : NTFS
IsReady : True
AvailableFreeSpace : 36340559872
TotalFreeSpace : 36340559872
TotalSize : 36413280256
RootDirectory : X:\
VolumeLabel : D_Drive
PS C:\>get-wmiobject win32_logicaldisk
DeviceID : C:
DriveType : 3
ProviderName :
FreeSpace : 39831252992
Size : 79900368896
VolumeName :
DeviceID : D:
DriveType : 5
ProviderName :
FreeSpace :
Size :
VolumeName :
DeviceID : X:
DriveType : 4
ProviderName : \\server01\public
FreeSpace : 36340559872
Size : 36413280256
VolumeName : D_Drive
PS C:\>get-wmiobject win32_networkconnection
LocalName RemoteName
-------------- ------------
x: \\server01\public
This example compares the types of file system drives that are displayed by Get-PSDrive to those displayed by using other methods. This example demonstrates different ways to display drives in Windows PowerShell, and it shows that temporary, session-specific drives created by using the New-PSDrive cmdlet are accessible only in Windows PowerShell. The first command uses Get-PSDrive to get all of the file system drives in the session. This includes the fixed drives (C: and D:), a mapped network drive (X:) that was created by using the Persist parameter of New-PSDrive, and two temporary Windows PowerShell drives (Y: and Z:) that were created by using New-PSDrive without the Persist parameter. A "net use" command, which displays Windows mapped network drives, displays only the X drive. It does not display the Y: and Z: drives that were created by New-PSDrive. It shows that the X: drive is also mapped to \Server01\Public. The third command uses the GetDrives method of the Microsoft .NET Framework System.IO.DriveInfo class. This command gets the Windows file system drives, including drive X:, but it does not get the temporary drives created by New-PSDrive. The fourth command uses the Get-WmiObject cmdlet to get the instances of the Win32_LogicalDisk class. It returns the C:, D:, and X: drives, but not the temporary drives created by New-PSDrive. The last command uses the Get-WmiObject cmdlet to display the instances of the Win32_NetworkConnection class. Like "net use", it returns only the persistent X: drive that was created by New-PSDrive.
###RELATED LINKS Online Version: New-PSDrive Remove-PSDrive about_Providers ##Get-PSProvider
###SYNOPSIS Gets information about the specified Windows PowerShell provider.
###SYNTAX TODO
###DESCRIPTION The Get-PSProvider cmdlet gets the Windows PowerShell providers in the current session. You can get a particular drive or all drives in the session. Windows PowerShell providers let you access a variety of data stores as though they were file system drives. For information about Windows PowerShell providers, see about_Providers.
###PARAMETERS
####PSProvider [<String[]>]
Specifies the name or names of the Windows PowerShell providers about which to retrieve information.
###INPUTS ####None You cannot pipe objects to this cmdlet.
###OUTPUTS ####System.Management.Automation.ProviderInfo Get-PSProvider returns objects that represent the Windows PowerShell providers in the session.
###NOTES ####System.Management.Automation.ProviderInfo
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-psprovider
This command displays a list of all available Windows PowerShell providers.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-psprovider f*, r* | format-list
This command displays a list of all Windows PowerShell providers with names that begin with the letter "f" or "r".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-psprovider | format-table name, module, pssnapin -auto
Name Module PSSnapIn
---- ------ --------
Test TestModule
WSMan Microsoft.WSMan.Management
Alias Microsoft.PowerShell.Core
Environment Microsoft.PowerShell.Core
FileSystem Microsoft.PowerShell.Core
Function Microsoft.PowerShell.Core
Registry Microsoft.PowerShell.Core
Variable Microsoft.PowerShell.Core
Certificate Microsoft.PowerShell.Security
PS C:\>get-psprovider | where {$_.pssnapin -eq "Microsoft.PowerShell.Security"}
Name Capabilities Drives
---- ------------ ------
Certificate ShouldProcess {cert}
These commands find the Windows PowerShell snap-ins or modules that added providers to your session. All Windows PowerShell elements, including providers, originate in a snap-in or in a module. These commands use the PSSnapin and Module properties of the ProviderInfo object that Get-PSProvider returns. The values of these properties contain the name of the snap-in or module that adds the provider. The first command gets all of the providers in the session and formats them in a table with the values of their Name, Module, and PSSnapin properties. The second command uses the Where-Object cmdlet to get the providers that come from the Microsoft.PowerShell.Security snap-in.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>resolve-path ~
Path
----
C:\Users\User01
PS C:\>(get-psprovider FileSystem).home
C:\Users\User01
This example shows that the tilde symbol (~) represents the value of the Home property of the FileSystem provider. The Home property value is optional, but for the FileSystem provider, it is defined as $env:homedrive$env:homepath or $home.
###RELATED LINKS Online Version: about_Providers ##Get-Service
###SYNOPSIS Gets the services on a local or remote computer.
###SYNTAX TODO
###DESCRIPTION The Get-Service cmdlet gets objects that represent the services on a local computer or on a remote computer, including running and stopped services. You can direct Get-Service to get only particular services by specifying the service name or display name of the services, or you can pipe service objects to Get-Service.
###PARAMETERS
####ComputerName [<String[]>]
Gets the services running on the specified computers. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-Service even if your computer is not configured to run remote commands.
####DependentServices [<SwitchParameter>]
Gets only the services that depend upon the specified service. By default, Get-Service gets all services.
####DisplayName <String[]>
Specifies the display names of services to be retrieved. Wildcards are permitted. By default, Get-Service gets all services on the computer.
####Exclude [<String[]>]
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####Include [<String[]>]
Retrieves only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####InputObject [<ServiceController[]>]
Specifies ServiceController objects representing the services to be retrieved. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe a service object to Get-Service.
####Name [<String[]>]
Specifies the service names of services to be retrieved. Wildcards are permitted. By default, Get-Service gets all of the services on the computer.
####RequiredServices [<SwitchParameter>]
Gets only the services that this service requires. This parameter gets the value of the ServicesDependedOn property of the service. By default, Get-Service gets all services.
###INPUTS ####System.ServiceProcess.ServiceController, System.String You can pipe a service object or a service name to Get-Service.
###OUTPUTS ####System.ServiceProcess.ServiceController Get-Service returns objects that represent the services on the computer.
###NOTES ####System.ServiceProcess.ServiceController You can also refer to Get-Service by its built-in alias, "gsv". For more information, see about_Aliases. Get-Service can display services only when the current user has permission to see them. If Get-Service does not display services, you might not have permission to see them. To find the service name and display name of each service on your system, type "get-service". The service names appear in the Name column, and the display names appear in the DisplayName column. When you sort in ascending order by status value, "Stopped" services appear before "Running" services. The Status property of a service is an enumerated value in which the names of the statuses represent integer values. The sort is based on the integer value, not the name. "Running" appears before "Stopped" because "Stopped" has a value of "1", and "Running" has a value of "4".
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>get-service
This command retrieves all of the services on the system. It behaves as though you typed "get-service *". The default display shows the status, service name, and display name of each service.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-service wmi*
This command retrieves services with service names that begin with "WMI" (the acronym for Windows Management Instrumentation).
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-service -displayname *network*
This command displays services with a display name that includes the word "network". Searching the display name finds network-related services even when the service name does not include "Net", such as xmlprov, the Network Provisioning Service.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-service -name win* -exclude winrm
These commands get only the services with service names that begin with "win", except for the WinRM service.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>get-service | where-object {$_.Status -eq "Running"}
This command displays only the services that are currently running. It uses the Get-Service cmdlet to get all of the services on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects only the services with a Status property that equals "Running". Status is only one property of service objects. To see all of the properties, type "get-service | get-member".
-------------------------- EXAMPLE 6 --------------------------
PS C:\>get-service -computername Server02
This command gets the services on the Server02 remote computer. Because the ComputerName parameter of Get-Service does not use Windows PowerShell remoting, you can use this parameter even if the computer is not configured for remoting in Windows PowerShell.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>get-service | where-object {$_.DependentServices} | format-list -property Name, DependentServices, @{Label="NoOfDependentServices"; Expression={$_.dependentservices.count}}
Name : AudioEndpointBuilder
DependentServices : {AudioSrv}
NoOfDependentServices : 1
Name : Dhcp
DependentServices : {WinHttpAutoProxySvc}
NoOfDependentServices : 1
...
These commands list the services on the computer that have dependent services. The first command uses the Get-Service cmdlet to get the services on the computer. A pipeline operator (|) sends the services to the Where-Object cmdlet, which selects the services whose DependentServices property is not null. Another pipeline operator sends the results to the Format-List cmdlet. The command uses its Property parameter to display the name of the service, the name of the dependent services, and a calculated property that displays the number of dependent services that each service has.
-------------------------- EXAMPLE 8 --------------------------
PS C:\>get-service s* | sort-object status
Status Name DisplayName
------ ---- -----------
Stopped stisvc Windows Image Acquisition (WIA)
Stopped SwPrv MS Software Shadow Copy Provider
Stopped SysmonLog Performance Logs and Alerts
Running Spooler Print Spooler
Running srservice System Restore Service
Running SSDPSRV SSDP Discovery Service
Running ShellHWDetection Shell Hardware Detection
Running Schedule Task Scheduler
Running SCardSvr Smart Card
Running SamSs Security Accounts Manager
Running SharedAccess Windows Firewall/Internet Connectio...
Running SENS System Event Notification
Running seclogon Secondary Logon
PS C:\>get-service s* | sort-object status -descending
Status Name DisplayName
------ ---- -----------
Running ShellHWDetection Shell Hardware Detection
Running SharedAccess Windows Firewall/Internet Connectio...
Running Spooler Print Spooler
Running SSDPSRV SSDP Discovery Service
Running srservice System Restore Service
Running SCardSvr Smart Card
Running SamSs Security Accounts Manager
Running Schedule Task Scheduler
Running SENS System Event Notification
Running seclogon Secondary Logon
Stopped SysmonLog Performance Logs and Alerts
Stopped SwPrv MS Software Shadow Copy Provider
Stopped stisvc Windows Image Acquisition (WIA)
This command shows that when you sort services in ascending order by the value of their Status property, stopped services appear before running services. This happens because the value of Status is an enumeration, in which "Stopped" has a value of "1", and "Running" has a value of 4. To list running services first, use the Descending parameter of the Sort-Object cmdlet.
-------------------------- EXAMPLE 9 --------------------------
PS C:\>get-service -name winrm -computername localhost, Server01, Server02 | format-table -property MachineName, Status, Name, DisplayName -auto
MachineName Status Name DisplayName
------------ ------ ---- -----------
localhost Running WinRM Windows Remote Management (WS-Management)
Server01 Running WinRM Windows Remote Management (WS-Management)
Server02 Running WinRM Windows Remote Management (WS-Management)
This command uses the Get-Service cmdlet to run a "Get-Service Winrm" command on two remote computers and the local computer ("localhost"). The Get-Service command runs on the remote computers, and the results are returned to the local computer. A pipeline operator (|) sends the results to the Format-Table cmdlet, which formats the services as a table. The Format-Table command uses the Property parameter to specify the properties displayed in the table, including the MachineName property.
-------------------------- EXAMPLE 10 --------------------------
PS C:\>get-service winrm -requiredServices
This command gets the services that the WinRM service requires. The command returns the value of the ServicesDependedOn property of the service.
-------------------------- EXAMPLE 11 --------------------------
PS C:\>"winrm" | get-service
This command gets the WinRM service on the local computer. This example shows that you can pipe a service name string (enclosed in quotation marks) to Get-Service.
###RELATED LINKS Online Version: New-Service Restart-Service Resume-Service Set-Service Start-Service Stop-Service Suspend-Service ##Get-Transaction
###SYNOPSIS Gets the current (active) transaction.
###SYNTAX TODO
###DESCRIPTION The Get-Transaction cmdlet gets an object that represents the current transaction in the session. This cmdlet never returns more than one object, because only one transaction is active at a time. If you start one or more independent transactions (by using the Independent parameter of Start-Transaction), the most recently started transaction is active, and that is the transaction that Get-Transaction returns. When all active transactions have either been rolled back or committed, Get-Transaction shows the transaction that was most recently active in the session. The Get-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_Transactions.
###PARAMETERS
###INPUTS ####None You cannot pipe objects to this cmdlet.
###OUTPUTS ####System.Management.Automation.PSTransaction Get-Transaction returns an object that represents the current transaction.
###NOTES ####System.Management.Automation.PSTransaction
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>start-transaction
PS C:\>get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
This command uses the Get-Transaction cmdlet to get the current transaction.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-transaction | get-member
Name MemberType Definition
---- ---------- ----------
Dispose Method System.Void Dispose(), System.Void Dispose(Boolean disposing)
Equals Method System.Boolean Equals(Object obj)
GetHashCode Method System.Int32 GetHashCode()
GetType Method System.Type GetType()
ToString Method System.String ToString()
IsCommitted Property System.Boolean IsCommitted {get;}
IsRolledBack Property System.Boolean IsRolledBack {get;}
RollbackPreference Property System.Management.Automation.RollbackSeverity RollbackPreference {get;}
SubscriberCount Property System.Int32 SubscriberCount {get;set;}
This command uses the Get-Member cmdlet to show the properties and methods of the transaction object.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>cd hklm:\software
HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> New-Item MyCompany -UseTransaction
HKLM:\SOFTWARE> Undo-Transaction
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ----------
Error 0 RolledBack
This command shows the property values of a transaction object for a transaction that has been rolled back.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>cd hklm:\software
HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> New-Item MyCompany -UseTransaction
HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ---------
Error 1 Committed
This command shows the property values of a transaction object for a transaction that has been committed.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>cd hklm:\software
HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> New-Item MyCompany -UseTransaction
HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> New-Item MyCompany2 -UseTransaction
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 Active
HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ---------
Error 1 Committed
This example shows the effect on the transaction object of starting a transaction while another transaction is in progress. Typically, this happens when a script that runs a transaction includes a function or calls a script that contains another complete transaction. Unless the second Start-Transaction command includes the Independent parameter, Start-Transaction does not create a new transaction. Instead, it adds a second subscriber to the original transaction. The first Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter is part of the transaction. A second Start-Transaction command adds a subscriber to the transaction. The next New-Item command is also part of the transaction. The first Get-Transaction command shows the multi-subscriber transaction. Notice that the subscriber count is 2. The first Complete-Transaction command does not commit the transaction, but it reduces the subscriber count to 1. The second Complete-Transaction command commits the transaction.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount IsRolledBack IsCommitted
------------------ --------------- ------------ -----------
Error 1 False False
HKLM:\SOFTWARE> Start-Transaction -Independent
HKLM:\SOFTWARE> Get-Transaction
RollbackPreference SubscriberCount IsRolledBack IsCommitted
------------------ --------------- ------------ -----------
Error 1 False False
HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction
HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction
This example shows the effect on the transaction object of starting an independent transaction while another transaction is in progress. The first Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter is part of the transaction. A second Start-Transaction command adds a subscriber to the transaction. The next New-Item command is also part of the transaction. The first Get-Transaction command shows the multi-subscriber transaction. Note that the subscriber count is 2. The Complete-Transaction command reduces the subscriber count to 1, but it does not commit the transaction. The second Complete-Transaction command commits the transaction.
###RELATED LINKS Online Version: Complete-Transaction Start-Transaction Undo-Transaction Use-Transaction about_Providers about_Transactions ##Get-WmiObject
###SYNOPSIS Gets instances of Windows Management Instrumentation (WMI) classes or information about the available classes.
###SYNTAX TODO
###DESCRIPTION Starting in Windows PowerShell 3.0, this cmdlet has been superseded by Get-CimInstance. The Get-WmiObject cmdlet gets instances of WMI classes or information about the available WMI classes. To specify a remote computer, use the ComputerName parameter. If the List parameter is specified, the cmdlet gets information about the WMI classes that are available in a specified namespace. If the Query parameter is specified, the cmdlet runs a WMI query language (WQL) statement.
The Get-WmiObject cmdlet does not use Windows PowerShell remoting to perform remote operations. You can use the ComputerName parameter of the Get-WmiObject cmdlet even if your computer does not meet the requirements for Windows PowerShell remoting or is not configured for remoting in Windows PowerShell. Beginning in Windows PowerShell 3.0, the __Server property of the object that Get-WmiObject returns has a PSComputerName alias. This makes it easier to include the source computer name in output and reports.
###PARAMETERS
####Amended [<SwitchParameter>]
Gets or sets a value that indicates whether the objects that are returned from WMI should contain amended information. Typically, amended information is localizable information, such as object and property descriptions, that is attached to the WMI object.
####AsJob [<SwitchParameter>]
Runs the command as a background job. Use this parameter to run commands that take a long time to finish. When you use the AsJob parameter, the command returns an object that represents the background job and then displays the command prompt. You can continue to work in the session while the job finishes. If Get-WmiObject is used on a remote computer, the job is created on the local computer, and the results from remote computers are automatically returned to the local computer. To manage the job, use the cmdlets that contain the Job cmdlets. To get the job results, use the Receive-Job cmdlet. Note: To use this parameter with remote computers, the local and remote computers must be configured for remoting. Additionally, you must start Windows PowerShell by using the "Run as administrator" option in Windows Vista and later versions of Windows. For more information, see about_Remote_Requirements. For more information about Windows PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
####Authentication [<AuthenticationLevel>]
Specifies the authentication level to be used with the WMI connection. Valid values are: -1: Unchanged 0: Default 1: None (No authentication in performed.) 2: Connect (Authentication is performed only when the client establishes a relationship with the application.) 3: Call (Authentication is performed only at the beginning of each call when the application receives the request.) 4: Packet (Authentication is performed on all the data that is received from the client.) 5: PacketIntegrity (All the data that is transferred between the client and the application is authenticated and verified.) 6: PacketPrivacy (The properties of the other authentication levels are used, and all the data is encrypted.)
####Authority [<String>]
Specifies the authority to use to authenticate the WMI connection. You can specify standard NTLM or Kerberos authentication. To use NTLM, set the authority setting to ntlmdomain:, where identifies a valid NTLM domain name. To use Kerberos, specify kerberos:<ServerName>". You cannot include the authority setting when you connect to the local computer.
####Class <String>
Specifies the name of a WMI class. When this parameter is used, the cmdlet retrieves instances of the WMI class.
####ComputerName [<String[]>]
Specifies the target computer for the management operation. Enter a fully qualified domain name, a NetBIOS name, or an IP address. When the remote computer is in a different domain than the local computer, the fully qualified domain name is required. The default is the local computer. To specify the local computer, such as in a list of computer names, use "localhost", the local computer name, or a dot (.). This parameter does not rely on Windows PowerShell remoting, which uses WS-Management. You can use the ComputerName parameter of Get-WmiObject even if your computer is not configured to run WS-Management remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01", "Domain01\User01", or [email protected]. Or, enter a PSCredential object, such as an object that is returned by the Get-Credential cmdlet. When you type a user name, you are prompted for a password.
####DirectRead [<SwitchParameter>]
Specifies whether direct access to the WMI provider is requested for the specified class without any regard to its base class or to its derived classes.
####EnableAllPrivileges [<SwitchParameter>]
Enables all the privileges of the current user before the command makes the WMI call.
####Filter [<String>]
Specifies a Where clause to use as a filter. Uses the syntax of the WMI Query Language (WQL). Important: Do not include the Where keyword in the value of the parameter. For example, the following commands return only the logical disks that have a DeviceID of 'c:' and services that have the name 'WinRM' without using the Where keyword. Get-WmiObject Win32_LogicalDisk -filter "DeviceID = 'c:' " Get-WmiObject win32_service -filter "name='WinRM'"
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use. Valid values are: 0: Default. Reads the local registry for the default impersonation level , which is usually set to "3: Impersonate". 1: Anonymous. Hides the credentials of the caller. 2: Identify. Allows objects to query the credentials of the caller. 3: Impersonate. Allows objects to use the credentials of the caller. 4: Delegate. Allows objects to permit other objects to use the credentials of the caller.
####List [<SwitchParameter>]
Gets the names of the WMI classes in the WMI repository namespace that is specified by the Namespace parameter. If you specify the List parameter, but not the Namespace parameter, Get-WmiObject uses the Root\Cimv2 namespace by default. This cmdlet does not use the Default Namespace registry entry in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\Scripting registry key to determine the default namespace.
####Locale [<String>]
Specifies the preferred locale for WMI objects. Enter a value in MS_ format.
####Namespace [<String>]
When used with the Class parameter, the Namespace parameter specifies the WMI repository namespace where the specified WMI class is located. When used with the List parameter, it specifies the namespace from which to gather WMI class information.
####Property [<String[]>]
Gets the specified WMI class properties. Enter the property names.
####Query <String>
Runs the specified WMI Query Language (WQL) statement. This parameter does not support event queries.
####Recurse [<SwitchParameter>]
Searches the current namespace and all other namespaces for the class name that is specified by the Class parameter.
####ThrottleLimit [<Int32>]
Specifies the maximum number of WMI operations that can be executed simultaneously. This parameter is valid only when the AsJob parameter is used in the command.
###INPUTS ####None You cannot pipe input to Get-WmiObject.
###OUTPUTS ####PSObject or System.Management.Automation.RemotingJob When you use the AsJob parameter, the cmdlet returns a job object. Otherwise, the object that Get-WmiObject returns depends on the value of the Class parameter.
###NOTES ####PSObject or System.Management.Automation.RemotingJob To access WMI information on a remote computer, the cmdlet must run under an account that is a member of the local administrators group on the remote computer. Or, the default access control on the WMI namespace of the remote repository can be changed to give access rights to other accounts. Only some of the properties of each WMI class are displayed by default. The set of properties that is displayed for each WMI class is specified in the Types.ps1xml configuration file. To get all properties of a WMI object, use the Get-Member or Format-List cmdlets.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-WmiObject -Class Win32_Process
This command get the processes on the local computer. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-WmiObject -Class Win32_Service -ComputerName 127.0.0.1
This command gets the services on a remote computer. It uses the ComputerName parameter to specify the Internet Protocol (IP) address, 127.0.0.1. By default, the current account must be a member of the Administrators group on the remote computer. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Get-WmiObject -Namespace "root/default" -List
This command gets the WMI classes in the root or default namespace of the local computer. -------------------------- EXAMPLE 4 --------------------------
PS C:\>Get-WmiObject -Query "select * from win32_service where name='WinRM'" -ComputerName Server01, Server02 | Format-List -Property PSComputerName, Name, ExitCode, Name, ProcessID, StartMode, State, Status
PSComputerName : SERVER01
Name : WinRM
ExitCode : 0
Name : WinRM
ProcessID : 844
StartMode : Auto
State : Running
Status : OK
PSComputerName : SERVER02
Name : WinRM
ExitCode : 0
Name : WinRM
ProcessID : 932
StartMode : Auto
State : Running
Status : OK
This command gets the WinRM service on the computers that are specified by the value of the ComputerName parameter. A pipeline operator (|) sends the output to the Format-List cmdlet, which adds the PSComputerName property to the default output. This makes it easy to see the computer on which the service resides. PSComputerName is an alias of the __Server property of the objects that Get-WmiObject returns. This alias is introduced in Windows PowerShell 3.0. -------------------------- EXAMPLE 5 --------------------------
PS C:\>(Get-WmiObject -Class Win32_Service -Filter "name='WinRM'" -ComputerName Server01).StopService()
This command stops the WinRM service on the Server01 remote computer. The command uses a Get-WmiObject command to get the WinRM service on Server01. Then, it invokes the StopService method of the Win32_Service WMI class on the object that the Get-WmiObject command returns. This command is an alternative to using the Stop-Service cmdlet. -------------------------- EXAMPLE 6 --------------------------
PS C:\>Get-WmiObject -Class Win32_Bios | Format-List -Property
Status : OK
Name : Phoenix ROM BIOS PLUS Version 1.10 A05
Caption : Phoenix ROM BIOS PLUS Version 1.10 A05
SMBIOSPresent : True
__GENUS : 2
__CLASS : Win32_BIOS
__SUPERCLASS : CIM_BIOSElement
__DYNASTY : CIM_ManagedSystemElement
__RELPATH : Win32_BIOS.Name="Phoenix ROM BIOS PLUS Version 1.10 …
__PROPERTY_COUNT : 27
__DERIVATION : {CIM_BIOSElement, CIM_SoftwareElement, CIM_LogicalElement,…
__SERVER : Server01
__NAMESPACE : root\cimv2
__PATH : \\SERVER01\root\cimv2:Win32_BIOS.Name="Phoenix ROM BIOS
BiosCharacteristics : {7, 9, 10, 11...}
BIOSVersion : {DELL - 15, Phoenix ROM BIOS PLUS Version 1.10 A05}
BuildNumber :
CodeSet :
CurrentLanguage : en|US|iso8859-1
Description : Phoenix ROM BIOS PLUS Version 1.10 A05
IdentificationCode :
InstallableLanguages : 1
InstallDate :
LanguageEdition :
ListOfLanguages : {en|US|iso8859-1}
Manufacturer : Dell Inc.
OtherTargetOS :
PrimaryBIOS : True
ReleaseDate : 20101103000000.000000+000
SerialNumber : 8VDM9P1
SMBIOSBIOSVersion : A05
SMBIOSMajorVersion : 2
SMBIOSMinorVersion : 6SoftwareElementID : Phoenix ROM BIOS PLUS Version 1.10 A05
SoftwareElementState : 3
TargetOperatingSystem : 0
Version : DELL - 15
Scope : System.Management.ManagementScope
Path : \\SERVER01\root\cimv2:Win32_BIOS.Name="Phoenix ROM BIOS
Options : System.Management.ObjectGetOptions
ClassPath : \\JUNE-PC\root\cimv2:Win32_BIOS
Properties : {BiosCharacteristics, BIOSVersion, BuildNumber, Caption...}
SystemProperties : {__GENUS, __CLASS, __SUPERCLASS, __DYNASTY...}
Qualifiers : {dynamic, Locale, provider, UUID}
Site :
Container :
This command gets the BIOS on the local computer. The command uses a value of all (*) for the Property parameter of the Format-List cmdlet to display all properties of the returned object in a list. By default, only a subset (defined in the Types.ps1xml configuration file) are displayed. -------------------------- EXAMPLE 7 --------------------------
PS C:\>Get-WmiObject Win32_Service -Credential FABRIKAM\administrator Computer Fabrikam
This command uses the Credential parameter of the Get-WmiObject cmdlet to get the services on a remote computer. The value of the Credential parameter is a user account name. The user is prompted for a password.
###RELATED LINKS Online Version: Get-WSManInstance Invoke-WSManAction New-WSManInstance Remove-WSManInstance Invoke-WmiMethod Remove-WmiObject Set-WmiInstance ##Invoke-Item
###SYNOPSIS Performs the default action on the specified item.
###SYNTAX TODO
###DESCRIPTION The Invoke-Item cmdlet performs the default action on the specified item. For example, it runs an executable file or opens a document file in the application associated with the document file type. The default action depends on the type of item and is determined by the Windows PowerShell provider that provides access to the data.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Include [<String[]>]
Performs the default action only on the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies a path to the item. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the path to the selected item.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Invoke-Item.
###OUTPUTS ####None The command does not generate any output. However, output might be generated by the item that it invokes.
###NOTES ####None The Invoke-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>invoke-item C:\Test\aliasApr04.doc
This command opens the file aliasApr04.doc in Microsoft Office Word. In this case, opening in Word is the default action for .doc files.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>invoke-item "C:\Documents and Settings\Lister\My Documents\*.xls"
This command opens all of the Microsoft Office Excel spreadsheets in the C:\Documents and Settings\Lister\My Documents folder. Each spreadsheet is opened in a new instance of Excel. In this case, opening in Excel is the default action for .xls files.
###RELATED LINKS Online Version: Clear-Item Copy-Item Get-Item Invoke-Command Move-Item New-Item Remove-Item Rename-Item Set-Item about_Providers ##Invoke-WmiMethod
###SYNOPSIS Calls Windows Management Instrumentation (WMI) methods.
###SYNTAX TODO
###DESCRIPTION The Invoke-WmiMethod cmdlet calls the methods of WMI objects. New CIM cmdlets, introduced Windows PowerShell 3.0, perform the same tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) standards and with the Common Information Model (CIM) standard, which enables the cmdlets to use the same techniques to manage Windows computers and those running other operating systems. Instead of using Invoke-WmiMethod, consider using Invoke-CimMethod.
###PARAMETERS
####ArgumentList [<Object[]>]
Specifies the parameters to pass to the called method. The value of this parameter must be an array of objects, and they must appear in the order required by the called method (note that new Invoke-CimCommand does not have these limitations). To determine the order in which to list those objects, run the GetMethodParameters() method on the WMI class, as illustrated in Example 1, near the end of this topic. Important: If the first value is an array that contains more than one element, a second value of $null is required. Otherwise, the command generates an error, such as "Unable to cast object of type 'System.Byte' to type 'System.Array'.". An example using an array of objects ($binSD) followed by a null value ($null) follows: PS C:>$acl = get-acl test.txt PS C:>$binSD = $acl.GetSecurityDescriptorBinaryForm() PS C:>invoke-wmimethod -class Win32_SecurityDescriptorHelper -Name BinarySDToSDDL -argumentlist $binSD, $null
####AsJob [<SwitchParameter>]
Runs the command as a background job. Use this parameter to run commands that take a long time to finish. When you use the AsJob parameter, the command returns an object that represents the background job and then displays the command prompt. You can continue to work in the session while the job finishes. If Invoke-WmiMethod is used against a remote computer, the job is created on the local computer, and the results from remote computers are automatically returned to the local computer. To manage the job, use the cmdlets that contain the Job noun (the Job cmdlets). To get the job results, use the Receive-Job cmdlet. Note: To use this parameter with remote computers, the local and remote computers must be configured for remoting. Additionally, you must start Windows PowerShell by using the "Run as administrator" option in Windows Vista and later versions of Windows. For more information, see about_Remote_Requirements. For more information about Windows PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
####Authentication [<AuthenticationLevel>]
Specifies the authentication level to be used with the WMI connection. Valid values are: -1: Unchanged 0: Default 1: None (No authentication in performed.) 2: Connect (Authentication is performed only when the client establishes a relationship with the application.) 3: Call (Authentication is performed only at the beginning of each call when the application receives the request.) 4: Packet (Authentication is performed on all the data that is received from the client.) 5: PacketIntegrity (All the data that is transferred between the client and the application is authenticated and verified.) 6: PacketPrivacy (The properties of the other authentication levels are used, and all the data is encrypted.)
####Authority [<String>]
Specifies the authority to use to authenticate the WMI connection. You can specify standard NTLM or Kerberos authentication. To use NTLM, set the authority setting to ntlmdomain:, where identifies a valid NTLM domain name. To use Kerberos, specify kerberos:<DomainName\ServerName>. You cannot include the authority setting when you connect to the local computer.
####Class <String>
Specifies the WMI class that contains a static method to call.
####ComputerName [<String[]>]
Runs the command on the specified computers. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more computers. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01", "Domain01\User01", or [email protected]. Or, enter a PSCredential object, such as an object that is returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.
####EnableAllPrivileges [<SwitchParameter>]
Enables all the privileges of the current user before the command makes the WMI call.
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use. Valid values are: 0: Default (Reads the local registry for the default impersonation level, which is usually set to "3: Impersonate".) 1: Anonymous (Hides the credentials of the caller.) 2: Identify (Allows objects to query the credentials of the caller.) 3: Impersonate (Allows objects to use the credentials of the caller.) 4: Delegate (Allows objects to permit other objects to use the credentials of the caller.)
####InputObject <ManagementObject>
Specifies a ManagementObject object to use as input. When this parameter is used, all other parameters except the Flag and Argument parameters are ignored.
####Locale [<String>]
Specifies the preferred locale for WMI objects. Specify the value of the Locale parameter as an array in the MS_ format in the preferred order.
####Name <String>
Specifies the name of the method to be invoked. This parameter is mandatory and cannot be null or empty.
####Namespace [<String>]
When used with the Class parameter, this parameter specifies the WMI repository namespace where the referenced WMI class or object is located.
####Path <String>
Specifies the WMI object path of a WMI class, or specifies the WMI object path of an instance of a WMI class. The class or the instance that you specify must contain the method that is specified in the Name parameter.
####ThrottleLimit [<Int32>]
Allows the user to specify a throttling value for the number of WMI operations that can be executed simultaneously. This parameter is used together with the AsJob parameter. The throttle limit applies only to the current command, not to the session or to the computer.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None This cmdlet does not accept any input.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>([wmiclass]'Win32_Volume').GetMethodParameters('Format')
__GENUS : 2
__CLASS : __PARAMETERS
__SUPERCLASS :
__DYNASTY : __PARAMETERS
__RELPATH :
__PROPERTY_COUNT : 6
__DERIVATION : {}
__SERVER :
__NAMESPACE :
__PATH :
ClusterSize : 0
EnableCompression : False
FileSystem : NTFS
Label :
QuickFormat : False
Version : 0
PSComputerName :
To invoke WMI in PowerShell 3.0 differs from alternate methods, and requires that object values are entered in a specific order. This command lists the required order of the objects.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>([Wmiclass]'Win32_Process').GetMethodParameters('Create')
__GENUS : 2
__CLASS : __PARAMETERS
__SUPERCLASS :
__DYNASTY : __PARAMETERS
__RELPATH :
__PROPERTY_COUNT : 3
__DERIVATION : {}
__SERVER :
__NAMESPACE :
__PATH :
CommandLine :
CurrentDirectory :
ProcessStartupInformation :
PSComputerName :
PS C:\>invoke-wmimethod -path win32_process -name create -argumentlist notepad.exe
__GENUS : 2
__CLASS : __PARAMETERS
__SUPERCLASS :
__DYNASTY : __PARAMETERS
__RELPATH :
__PROPERTY_COUNT : 2
__DERIVATION : {}
__SERVER :
__NAMESPACE :
__PATH :
ProcessId : 11312
ReturnValue : 0
PSComputerName :
The following two commands start an instance of Notepad by calling the Create method of the Win32_Process class.
Note: The ReturnValue property is populated with a 0, and the ProcessId property is populated with an integer (the next process ID number) if the command is completed.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>invoke-wmimethod -path "CIM_DataFile.Name='C:\scripts\test.txt'" -Name Rename -ArgumentList "C:\scripts\test_bu.txt"
__GENUS : 2
__CLASS : __PARAMETERS
__SUPERCLASS :
__DYNASTY : __PARAMETERS
__RELPATH :
__PROPERTY_COUNT : 1
__DERIVATION : {}
__SERVER :
__NAMESPACE :
__PATH :
ReturnValue : 0
This command renames a file. It uses the Path parameter to reference an instance of the CIM_DataFile class. Then, it applies the Rename method to that particular instance.
Note: The ReturnValue property is populated with a 0 if the command is completed.
###RELATED LINKS Online Version: Get-WSManInstance Invoke-WSManAction New-WSManInstance Remove-WSManInstance Get-WmiObject Remove-WmiObject Set-WmiInstance ##Join-Path
###SYNOPSIS Combines a path and a child path into a single path. The provider supplies the path delimiters.
###SYNTAX TODO
###DESCRIPTION The Join-Path cmdlet combines a path and child-path into a single path. The provider supplies the path delimiters.
###PARAMETERS
####ChildPath <String>
Specifies the elements to append to the value of Path. Wildcards are permitted. The ChildPath parameter is required, although the parameter name ("ChildPath") is optional.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Path <String[]>
Specifies the main path (or paths) to which the child-path is appended. Wildcards are permitted. The value of Path determines which provider joins the paths and adds the path delimiters. The Path parameter is required, although the parameter name ("Path") is optional.
####Resolve [<SwitchParameter>]
Displays the items that are referenced by the joined path.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter can only be used when a transaction is in progress. For more information, see about_Transactions.
###INPUTS ####System.String You can pipe a string that contains a path to Join-Path.
###OUTPUTS ####System.String Join-Path returns a string that contains the resulting path.
###NOTES ####System.String The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators. You can use the path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers. The Join-Path cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>join-path -path c:\win* -childpath System*
This command uses Join-Path to combine the "c:\Win*" path with the "System*" child path. The Windows PowerShell file system provider, FileSystem joins the path and adds the "" delimiter.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>join-path c:\win* System* -resolve
This command displays the files and folders that are referenced by joining the "c:\Win*" path and the "System*" child path. It displays the same files and folders as Get-ChildItem, but it displays the fully qualified path to each item. In this command, the Path and ChildPath optional parameter names are omitted.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>PS HKLM:\> join-path System *ControlSet* -resolve
This command displays the registry keys in the HKLM\System registry subkey that include "ControlSet". This example shows how to use Join-Path with the Windows PowerShell registry provider.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>join-path -path C:, D:, E:, F: -childpath New
This command uses Join-Path to combine multiple path roots with a child path.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>get-psdrive -psprovider filesystem | foreach {$_.root} | join-path -childpath Subdir
This command combines the roots of each Windows PowerShell file system drive in the console with the Subdir child path. The command uses the Get-PSDrive cmdlet to get the Windows PowerShell drives supported by the FileSystem provider. The ForEach statement selects only the Root property of the PSDriveInfo objects and combines it with the specified child path. The output shows that the Windows PowerShell drives on the computer included a drive mapped to the C:\Program Files directory.
###RELATED LINKS Online Version: Convert-Path Resolve-Path Split-Path Test-Path about_Providers ##Limit-EventLog
###SYNOPSIS Sets the event log properties that limit the size of the event log and the age of its entries.
###SYNTAX TODO
###DESCRIPTION The Limit-EventLog cmdlet sets the maximum size of a classic event log, how long each event must be retained, and what happens when the log reaches its maximum size. You can use it to limit the event logs on local or remote computers. The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.
###PARAMETERS
####ComputerName [<String[]>]
Specifies a remote computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Limit-EventLog even if your computer is not configured to run remote commands.
####LogName <String[]>
Specifies the event logs. Enter the log name (the value of the Log property; not the LogDisplayName) of one or more event logs , separated by commas. Wildcard characters are not permitted. This parameter is required.
####MaximumSize [<Int64>]
Specifies the maximum size of the event logs in bytes. Enter a value between 64 kilobytes (KB) and 4 gigabytes (GB). The value must be divisible by 64 KB (65536). This parameter specifies the value of the MaximumKilobytes property of the System.Diagnostics.EventLog object that represents a classic event log.
####OverflowAction [<OverflowAction>]
Specifies what happens when the event log reaches its maximum size. Valid values are: -- DoNotOverwrite: Existing entries are retained and new entries are discarded. -- OverwriteAsNeeded: Each new entry overwrites the oldest entry. -- OverwriteOlder: New events overwrite events older than the value specified by the MinimumRetentionDays property. If there are no events older than specified by the MinimumRetentionDays property value, new events are discarded. This parameter specifies the value of the OverflowAction property of the System.Diagnostics.EventLog object that represents a classic event log.
####RetentionDays [<Int32>]
Specifies the minimum number of days that an event must remain in the event log. This parameter specifies the value of the MinimumRetentionDays property of the System.Diagnostics.EventLog object that represents a classic event log.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None None
###OUTPUTS ####None None
###NOTES ####None To use Limit-EventLog on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. Limit-EventLog changes the properties of the System.Diagnostics.EventLog object that represents a classic event log. To see the current settings of the event log properties, type "get-eventlog -list".
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>limit-eventLog -logname "Windows PowerShell" -MaximumSize 20KB
This command increases the maximum size of the Windows PowerShell event log on the local computer to 20480 bytes (20 KB).
-------------------------- EXAMPLE 2 --------------------------
PS C:\>limit-eventlog -logname Security -comp Server01, Server02 -retentionDays 7
This command ensures that events in the Security log on the Server01 and Server02 computers are retained for at least 7 days.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$logs = get-eventlog -list | foreach {$_.log}
PS C:\>limit-eventlog -overflowaction OverwriteOlder -logname $logs
PS C:\>get-eventlog -list
Max(K) Retain OverflowAction Entries Log
------ ------ -------------- ------- ---
15,168 0 OverwriteOlder 3,412 Application
512 0 OverwriteOlder 0 DFS Replication
512 0 OverwriteOlder 17 DxStudio
10,240 7 OverwriteOlder 0 HardwareEvents
512 0 OverwriteOlder 0 Internet Explorer
512 0 OverwriteOlder 0 Key Management Service
16,384 0 OverwriteOlder 4 ODiag
16,384 0 OverwriteOlder 389 OSession Security
15,168 0 OverwriteOlder 19,360 System
15,360 0 OverwriteOlder 15,828 Windows PowerShell
These commands change the overflow action of all event logs on the local computer to "OverwriteOlder". The first command gets the log names of all of the logs on the local computer. The second command sets the overflow action. The third command displays the results.
###RELATED LINKS Online Version: Clear-EventLog Get-EventLog Limit-EventLog New-EventLog Remove-EventLog Show-EventLog Write-EventLog ##Move-Item
###SYNOPSIS Moves an item from one location to another.
###SYNTAX TODO
###DESCRIPTION The Move-Item cmdlet moves an item, including its properties, contents, and child items, from one location to another location. The locations must be supported by the same provider. For example, it can move a file or subdirectory from one directory to another or move a registry subkey from one key to another. When you move an item, it is added to the new location and deleted from its original location.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Destination [<String>]
Specifies the path to the location where the items are being moved. The default is the current directory. Wildcards are permitted, but the result must specify a single location. To rename the item being moved, specify a new name in the value of the Destination parameter.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to move an item that writes over an existing read-only item. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Moves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to the current location of the items. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Passes an object representing the item to the pipeline. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the current location of the items. The default is the current directory. Wildcards are permitted.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Move-Item.
###OUTPUTS ####None or an object representing the moved item. When you use the Passthru parameter, Move-Item generates an object representing the moved item. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or an object representing the moved item. Move-Item will move files between drives that are supported by the same provider, but it will move directories only within the same drive. Because a Move-Item command moves the properties, contents, and child items of an item, all moves are recursive by default. You can also refer to Move-Item by its built-in aliases, "move", "mv", and "mi". For more information, see about_Aliases. The Move-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>move-item -path C:\test.txt -destination E:\Temp\tst.txt
This command moves the Test.txt file from the C: drive to the E:\Temp directory and renames it from "test.txt" to "tst.txt".
-------------------------- EXAMPLE 2 --------------------------
PS C:\>move-item -path C:\Temp -destination C:\Logs
This command moves the C:\Temp directory and its contents to the C:\Logs directory. The Temp directory, and all of its subdirectories and files, then appear in the Logs directory.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>move-item -path .\*.txt -destination C:\Logs
This command moves all of the text files (*.txt) in the current directory (represented by a dot (.)) to the C:\Logs directory.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>Get-ChildItem -Path .\*.txt -Recurse | Move-Item -Destination C:\TextFiles
This command moves all of the text files from the current directory and all subdirectories, recursively, to the C:\TextFiles directory. The command uses the Get-ChildItem cmdlet to get all of the child items in the current directory (represented by the dot [.]) and its subdirectories that have a *.txt file name extension. It uses the Recurse parameter to make the retrieval recursive and the Include parameter to limit the retrieval to *.txt files. The pipeline operator (|) sends the results of this command to Move-Item, which moves the text files to the TextFiles directory. If files being moved to C:\Textfiles have the same name, Move-Item displays an error and continues, but it moves only one file with each name to C:\Textfiles. The other files remain in their original directories. If the Textfiles directory (or any other element of the destination path) does not exist, the command fails. The missing directory is not created for you, even if you use the Force parameter. Move-Item moves the first item to a file called "Textfiles" and then displays an error explaining that the file already exists. Also, by default, Get-ChildItem does not move hidden files. To move hidden files, use the Force parameter with Get-ChildItem. Note: In Windows PowerShell 2.0, when using the Recurse parameter of the Get-ChildItem cmdlet, the value of the Path parameter must be a container. Use the Include parameter to specify the .txt file name extension filter (Get-ChildItem –Path .* -Include *.txt –Recurse | Move-Item -Destination C:\TextFiles).
-------------------------- EXAMPLE 5 --------------------------
PS C:\>move-item hklm:\software\mycompany\* hklm:\software\mynewcompany
This command moves the registry keys and values within the MyCompany registry key in HKLM\Software to the MyNewCompany key. The wildcard character (*) indicates that the contents of the MyCompany key should be moved, not the key itself. In this command, the optional Path and Destination parameter names are omitted.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>move-item -literalpath 'Logs[Sept`06]' -destination 'Logs[2006]'
This command moves the Logs[Sept06] directory (and its contents) into the Logs[2006] directory. The LiteralPath parameter is used instead of Path, because the original directory name includes left bracket and right bracket characters ("[" and "]"). The path is also enclosed in single quotation marks (' '), so that the backtick symbol () is not misinterpreted.
The Destination parameter does not require a literal path, because the Destination variable also must be enclosed in single quotation marks, because it includes brackets that can be misinterpreted.
###RELATED LINKS Online Version: Clear-Item Copy-Item Get-Item Invoke-Item New-Item Remove-Item Rename-Item Set-Item about_Providers ##Move-ItemProperty
###SYNOPSIS Moves a property from one location to another.
###SYNTAX TODO
###DESCRIPTION The Move-ItemProperty cmdlet moves a property of an item from one item to another item. For example, it can move a registry entry from one registry key to another registry key. When you move an item property, it is added to the new location and deleted from its original location.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Destination <String>
Specifies the path to the destination location.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to move properties to or from items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_Providers.
####Include [<String[]>]
Moves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to the current location of the property. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String[]>
Specifies the name of the property to be moved.
####PassThru [<SwitchParameter>]
Passes an object representing the item property. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the current location of the property. Wildcards are permitted.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Move-ItemProperty.
###OUTPUTS ####None or System.Management.Automation.PSCustomObject When you use the PassThru parameter, Move-ItemProperty generates a PSCustomObject representing the moved item property. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PSCustomObject The names of the Path, Destination, and Name parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Path, Destination, Name. If you include the parameter names, the parameters can appear in any order. You can also refer to Move-ItemProperty by its built-in alias, "mp". For more information, see about_Aliases. The Move-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>move-itemproperty HKLM:\Software\MyCompany\MyApp -Name `
Version -Destination HKLM:\Software\MyCompany\NewApp
This command moves the "Version" registry value, and its data, from the MyApp subkey to the NewApp subkey of the HKLM\Software\MyCompany registry key.
###RELATED LINKS Online Version: Clear-ItemProperty Copy-ItemProperty Get-ItemProperty New-ItemProperty Remove-ItemProperty Rename-ItemProperty Set-ItemProperty about_Providers ##New-EventLog
###SYNOPSIS Creates a new event log and a new event source on a local or remote computer.
###SYNTAX TODO
###DESCRIPTION This cmdlet creates a new classic event log on a local or remote computer. It can also register an event source that writes to the new log or to an existing log. The cmdlets that contain the EventLog noun (the Event log cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.
###PARAMETERS
####CategoryResourceFile [<String>]
Specifies the path to the file that contains category strings for the source events. This file is also known as the Category Message File. The file must be present on the computer on which the event log is being created. This parameter does not create or move files.
####ComputerName [<String[]>]
Creates the new event logs on the specified computers. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-EventLog even if your computer is not configured to run remote commands.
####LogName <String>
Specifies the name of the event log. If the log does not exist, New-EventLog creates the log and uses this value for the Log and LogDisplayName properties of the new event log. If the log exists, New-EventLog registers a new source for the event log.
####MessageResourceFile [<String>]
Specifies the path to the file that contains message formatting strings for the source events. This file is also known as the Event Message File. The file must be present on the computer on which the event log is being created. This parameter does not create or move files.
####ParameterResourceFile [<String>]
Specifies the path to the file that contains strings used for parameter substitutions in event descriptions. This file is also known as the Parameter Message File. The file must be present on the computer on which the event log is being created. This parameter does not create or move files.
####Source <String[]>
Specifies the names of the event log sources, such as application programs that write to the event log. This parameter is required.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Diagnostics.EventLogEntry
###NOTES ####System.Diagnostics.EventLogEntry To use New-EventLog on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. To create an event source in Windows Vista, Windows XP Professional, or Windows Server 2003, you must be a member of the Administrators group on the computer. When you create a new event log and a new event source, the system registers the new source for the new log, but the log is not created until the first entry is written to it. The operating system stores event logs as files. When you create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is the first eight characters of the Log property with an .evt file name extension.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>new-eventlog -source TestApp -logname TestLog -MessageResourceFile C:\Test\TestApp.dll
This command creates the TestLog event log on the local computer and registers a new source for it.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>$file = "C:\Program Files\TestApps\NewTestApp.dll"
PS C:\>new-eventlog -computername Server01 -source NewTestApp -logname Application -MessageResourceFile $file -CategoryResourceFile $file
This command adds a new event source, NewTestApp, to the Application log on the Server01 remote computer. The command requires that the NewTestApp.dll file is located on the Server01 computer.
###RELATED LINKS Online Version: Clear-EventLog Get-EventLog Limit-EventLog New-EventLog Remove-EventLog Show-EventLog Write-EventLog ##New-Item
###SYNOPSIS Creates a new item.
###SYNTAX TODO
###DESCRIPTION The New-Item cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, New-Item is used to create files and folders. In the registry, New-Item creates registry keys and entries. New-Item can also set the value of the items that it creates. For example, when creating a new file, New-Item can add initial content to the file.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell
####Force [<SwitchParameter>]
Allows the cmdlet to create an item that writes over an existing read-only item. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####ItemType [<String>]
Specifies the provider-specified type of the new item. Starting in Windows PowerShell 5.0, you can create symbolic links by specifying SymbolicLink as the value of this parameter.
####Name <String>
Specifies the name of the new item. You can specify the name of the new item in the Name or Path parameter value, and you can specify the path to the new item in the Name or Path parameter value.
####Path <String[]>
Specifies the path to the location of the new item. Wildcards are permitted. You can specify the name of the new item in the Name parameter, or include it in the Path parameter.
####Value [<Object>]
Specifies the value of the new item. You can also pipe a value to New-Item.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.Object You can pipe a value for the new item to the New-Item cmdlet.
###OUTPUTS ####System.Object New-Item returns the item that it creates.
###NOTES ####System.Object The New-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>new-item -path . -name testfile1.txt -itemtype "file" -value "This is a text string."
This command creates a text file named testfile1.txt in the current directory. The dot (.) in the value of the Path parameter indicates the current directory. The quoted text that follows the Value parameter is added to the file as content.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>new-item -path c:\ -name logfiles -itemtype directory
This command creates a directory named Logfiles in the C: drive. The ItemType parameter specifies that the new item is a directory, not a file or other file system object.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>new-item -path $profile -itemtype file -force
This command creates a Windows PowerShell profile in the path that is specified by the $profile variable. You can use profiles to customize Windows PowerShell. $Profile is an automatic (built-in) variable that stores the path and file name of the CurrentUser/CurrentHost profile. By default, the profile does not exist, even though Windows PowerShell stores a path and file name for it. In this command, the $profile variable represents the path to the file. The ItemType parameter specifies that the command creates a file. The Force parameter lets you create a file in the profile path, even when the directories in the path do not exist (Windows PowerShell creates them). After you use this command to create a profile, you can enter aliases, functions, and scripts in the profile to customize your shell. For more information, see about_Automatic_Variables and about_Profiles.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>new-item -itemtype directory -path c:\ps-test\scripts
This command creates a new Scripts directory in the C:\PS-Test directory. The name of the new directory item, Scripts, is included in the value of the Path parameter, instead of being specified in the value of the Name parameter. As indicated by the syntax, either command form is valid.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>new-item -itemtype file -path "c:\ps-test\test.txt", "c:\ps-test\Logs\test.log"
This command uses the New-Item cmdlet to create files in two different directories. Because the Path parameter takes multiple strings, you can use it to create multiple items.
###RELATED LINKS Online Version: Clear-Item Copy-Item Get-Item Invoke-Item Move-Item Remove-Item Rename-Item Set-Item about_Providers ##New-ItemProperty
###SYNOPSIS Creates a new property for an item and sets its value. For example, you can use New-ItemProperty to create and change registry values and data, which are properties of a registry key.
###SYNTAX TODO
###DESCRIPTION The New-ItemProperty cmdlet creates a new property for a specified item and sets its value. Typically, this cmdlet is used to create new registry values, because registry values are properties of a registry key item. This cmdlet does not add properties to an object. To add a property to an instance of an object, use the Add-Member cmdlet. To add a property to all objects of a particular type, edit the Types.ps1xml file.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to create a property on an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_Providers.
####Include [<String[]>]
The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String>
Specifies a name for the new property. If the property is a registry entry, this parameter specifies the name of the entry.
####Path <String[]>
Specifies the path to the item. This parameter identifies the item to which the new property will be added.
####PropertyType [<String>]
Specifies the type of property that will be added.
####Value [<Object>]
Specifies the property value. If the property is a registry entry, this parameter specifies the value of the entry.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe input to New-ItemProperty.
###OUTPUTS ####System.Management.Automation.PSCustomObject New-ItemProperty returns a custom object that contains the new property.
###NOTES ####System.Management.Automation.PSCustomObject The New-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>new-itemproperty -path HKLM:\Software\MyCompany -name NoOfEmployees -value 822
PS C:\>get-itemproperty hklm:\software\mycompany
PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
PSChildName : mycompany
PSDrive : HKLM
PSProvider : Microsoft.PowerShell.Core\Registry
NoOfLocations : 2
NoOfEmployees : 822
This command adds a new registry entry, NoOfEmployees, to the MyCompany key of the HKLM:\Software hive. The first command uses the Path parameter to specify the path to the MyCompany registry key. It uses the Name parameter to specify a name for the entry and the Value parameter to specify its value. The second command uses the Get-ItemProperty cmdlet to see the new registry entry.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-item -path HKLM:\Software\MyCompany | new-Itemproperty -name NoOfLocations -value 3
This command adds a new registry entry to a registry key. To specify the key, it uses a pipeline operator (|) to send an object representing the key to the New-ItemProperty cmdlet. The first part of the command uses the Get-Item cmdlet to get the MyCompany registry key. The pipeline operator (|) sends the results of the command to the New-ItemProperty cmdlet, which adds the new registry entry, NoOfLocations, and its value, 3, to the MyCompany key. This command works because the parameter-binding feature of Windows PowerShell associates the path of the RegistryKey object that Get-Item returns with the LiteralPath parameter of New-ItemProperty. For more information, see about_Pipelines.
###RELATED LINKS Online Version: Clear-ItemProperty Copy-ItemProperty Get-ItemProperty Move-ItemProperty Remove-ItemProperty Rename-ItemProperty Set-ItemProperty about_Providers ##New-PSDrive
###SYNOPSIS Creates temporary and persistent mapped network drives.
###SYNTAX TODO
###DESCRIPTION The New-PSDrive cmdlet creates temporary and persistent drives that are "mapped" to or associated with a location in a data store, such as a network drive, a directory on the local computer, or a registry key, and persistent Windows mapped network drives that are associated with a file system location on a remote computer. Temporary drives exist only in the current Windows PowerShell session and in sessions that you create in the current session. They can have any name that is valid in Windows PowerShell and can be mapped to any local or remote resource. You can use temporary Windows PowerShell drives to access data in the associated data store, just like you would do with any mapped network drive. You can change locations into the drive (using "set-location", "cd", or "chdir") and access the contents of the drive (using "get-item", "get-childitem", or "dir"). However, because temporary drives are known only to Windows PowerShell, you cannot access them by using File Explorer, Windows Management Instrumentation (WMI), Component Object Model (COM), or the Microsoft .NET Framework, or by using tools such as Net Use. New features are added to New-PSDrive in Windows PowerShell 3.0. -- Mapped network drives: You can use the Persist parameter of New-PSDrive to create Windows mapped network drives. Unlike temporary Windows PowerShell drives, Windows mapped network drives are not session-specific; they are saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and Net Use. Mapped network drives must have a drive-letter name and be connected to a remote file system location. -- External drives: When an external drive is connected to the computer, Windows PowerShell automatically adds a PSDrive to the file system that represents the new drive. You do not need to restart Windows PowerShell. Similarly, when an external drive is disconnected from the computer, Windows PowerShell automatically deletes the PSDrive that represents the removed drive. -- Credentials for UNC Paths: When the value of the Root parameter is a UNC path, such as \Server\Share, the credential specified in the value of the Credential parameter is used to create the PSDrive. Otherwise, the Credential parameter is not effective when creating new file system drives.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. Beginning in Windows PowerShell 3.0, when the value of the Root parameter is a UNC path, you can use credentials to create file system drives. This parameter is not supported by all Windows PowerShell providers.
####Description [<String>]
Specifies a brief text description of the drive. Type any string. To see the descriptions of all of the drives in the session, type "Get-PSDrive | Format-Table Name, Description". To see the description of a particular drives, type "(Get-PSDrive ).Description".
####Name <String>
Specifies a name for the new drive. For persistent mapped network drives, type a drive letter. For temporary Windows PowerShell drives, type any valid string; you are not limited to drive letters.
####Persist [<SwitchParameter>]
Creates a Windows mapped network drive. Mapped network drives are saved in Windows on the local computer. They are persistent, not session-specific, and can be viewed and managed in File Explorer and other tools. The name of the drive must be a letter, such as D or E. The value of the Root parameter must be a UNC path to a different computer. The value of the PSProvider parameter must be FileSystem. To disconnect a Windows mapped network drive, use the Remove-PSDrive cmdlet. When you disconnect a Windows mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. NOTE: Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credential of another user are not visible in session that started without explicit credentials or with the credentials of the current user.
####PSProvider <String>
Specifies the Windows PowerShell provider that supports drives of this type. For example, if the drives is associated with a network share or file system directory, the Windows PowerShell provider is "FileSystem". If the drive is associated with a registry key, the provider is "Registry". Temporary Windows PowerShell drives can be associated with any Windows PowerShell provider. Mapped network drives can be associated only with the FileSystem provider. To see a list of the providers in your Windows PowerShell session, use the Get-PSProvider cmdlet.
####Root <String>
Specifies the data store location to which a Windows PowerShell drive is mapped. For example, specify a network share (such as \Server01\Public), a local directory (such as C:\Program Files), or a registry key (such as HKLM:\Software\Microsoft). Temporary Windows PowerShell drives can be associated with a local or remote location on any supported provider drive. Mapped network drives can be associated only with a file system location on a remote computer.
####Scope [<String>]
Specifies a scope for the drive. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes (http://go.microsoft.com/fwlink/?LinkID=113260).
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Management.Automation.PSDriveInfo
###NOTES ####System.Management.Automation.PSDriveInfo The New-PSDrive cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information about providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credential of another user are not visible in session that started without explicit credentials or with the credentials of the current user.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>New-PSDrive -Name P -PSProvider FileSystem -Root \\Server01\Public
Name Provider Root
---- -------- ----
P FileSystem \\Server01\Public
This command creates a temporary Windows PowerShell drive named P: that is mapped to the \Server01\Public network share. It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell FileSystem provider, and the Root parameter to specify the network share. When the command completes, the contents of the \Server01\Public share appear in the P: drive. To see them, type: "dir P:". -------------------------- EXAMPLE 2 --------------------------
PS C:\>New-PSDrive -Name MyDocs -PSProvider FileSystem -Root "C:\Documents and Settings\User01\My Documents" -Description "Maps to my My Documents folder."
Name Provider Root
---- -------- ----
MyDocs FileSystem C:\Documents and Settings\User01\My Documents
This command creates a temporary Windows PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the "C:\Documents and Settings\User01\My Documents" directory on the local computer. It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell FileSystem provider, the Root parameter to specify the path to the My Documents folder, and the Description parameter to create a description of the drive. When the command completes, the contents of the My Documents folder appear in the MyDocs: drive. To see them, type: "dir MyDocs:". -------------------------- EXAMPLE 3 --------------------------
PS C:\>New-PSDrive -Name MyCompany -PSProvider Registry -Root HKLM:\Software\MyCompany
Name Provider Root
---- -------- ----
MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo...
This command creates a temporary Windows PowerShell drive that provides quick access to a frequently checked registry key. It creates a drive named MyCompany that is mapped to the HKLM\Software\MyCompany registry key. It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell Registry provider, and the Root parameter to specify the registry key. When the command completes, the contents of the MyCompany key appear in the MyCompany: drive. To see them, type: "dir MyCompany:". -------------------------- EXAMPLE 4 --------------------------
PS C:\>New-PSDrive -Name S -Root \\Server01\Scripts -Persist -PSProvider FileSystem
PS C:\> net use
Status Local Remote Network
---------------------------------------------------------
OK S: \\Server01\Scripts Microsoft Windows Network
This command creates the "S" mapped network drive on the local computer. The "S" drive is mapped to the \Server01\Scripts network share.
The command uses the New-PSDrive cmdlet to create the mapped network drive. It uses the Persist parameter to create a Windows mapped network drive that is saved on the local computer. The command uses the Name parameter to specify a letter name that Windows accepts and the Root parameter to specify a location on a remote computer. It uses the PSProvider parameter to specify the FileSystem provider.
The resulting drive can be viewed in other Windows PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use. -------------------------- EXAMPLE 5 --------------------------
The first command uses the New-PSDrive cmdlet to create a temporary Windows PowerShell drive called PSDrive: that is mapped to the \\Server01\Public network share.
PS C:\>New-PSDrive -Name PSDrive -PSProvider FileSystem -Root \\Server01\Public
The second command uses the Persist parameter of New-PSDrive to create the X: mapped network drive, which is also mapped to the \\Server01\Public network share.
PS C:\>New-PSDrive -Persist -Name X -PSProvider FileSystem -Root \\Server01\Public
Now, you can use the Get-PSDrive drive cmdlet to examine the two drives. The drives appear to be the same, although the network share name appears only in the root of the PSDrive: drive.
PS C:\>Get-PSDrive -Name PSDrive, X
Name Provider Root
---- -------- ----
PsDrive FileSystem \\Server01\public
X FileSystem X:\
The output of the Get-Member cmdlet shows that the drives have the same object type, System.Management.Automation.PSDriveInfo.
PS C:\>Get-PSDrive PSDrive, x | Get-Member
TypeName: System.Management.Automation.PSDriveInfo
Name MemberType Definition
---- ---------- ----------
CompareTo Method System.Int32 CompareTo(PSDriveInfo drive),
Equals Method System.Boolean Equals(Object obj),
GetHashCode Method System.Int32 GetHashCode()
...
However, a "net use" command, a Get-WmiObject command for the Win32_LogicalDisk class, and a Get-WmiObject command for the Win32_NetworkConnection class find only the persistent X: drive because Windows PowerShell temporary drives are known only to Windows PowerShell.If you close the Windows PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it needs to be persistent, and whether the drive needs to be visible to other Windows features.
PS C:\>net use
Status Local Remote Network
--------------------------------------------------------
OK X: \\contoso-pc\data Microsoft Windows Network
PS C:\>Get-WmiObject Win32_LogicalDisk | Format-Table -Property DeviceID
deviceid
--------
C:
D:
X:
PS C:\>Get-WmiObject Win32_NetworkConnection
LocalName RemoteName ConnectionState Status
--------- ---------- --------------- ------
X: \\products\public Disconnected Unavailable
This example shows the difference between a persistent mapped network drive and a temporary Windows PowerShell drive that is mapped to the same network share.
###RELATED LINKS Online Version: Get-PSDrive Remove-PSDrive about_Providers ##New-Service
###SYNOPSIS Creates a new Windows service.
###SYNTAX TODO
###DESCRIPTION The New-Service cmdlet creates a new entry for a Windows service in the registry and in the service database. A new service requires an executable file that executes during the service. The parameters of this cmdlet let you set the display name, description, startup type, and dependencies of the service.
###PARAMETERS
####BinaryPathName <String>
Specifies the path to the executable file for the service. This parameter is required.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one from the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
####DependsOn [<String[]>]
Specifies the names of other services upon which the new service depends. To enter multiple service names, use a comma to separate the names.
####Description [<String>]
Specifies a description of the service.
####DisplayName [<String>]
Specifies a display name for the service.
####Name <String>
Specifies the name of the service. This parameter is required.
####StartupType [<ServiceStartMode>]
Sets the startup type of the service. "Automatic" is the default. Valid values are: -- Manual: The service is started only manually, by a user (using the Service Control Manager) or by an application. -- Automatic: The service is to be started (or was started) by the operating system, at system start-up. If an automatically started service depends on a manually started service, the manually started service is also started automatically at system startup. -- Disabled: The service is disabled and cannot be started by a user or application.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.ServiceProcess.ServiceController New-Service returns an object that represents the new service.
###NOTES ####System.ServiceProcess.ServiceController To run this cmdlet on Windows Vista and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. To delete a service, use Sc.exe, or use the Get-WmiObject cmdlet to get the Win32_Service object that represents the service and then use the Delete method to delete the service. (The object that Get-Service returns does not have a delete method.) For an example, see the Examples section.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>new-service -name TestService -binaryPathName "C:\WINDOWS\System32\svchost.exe -k netsvcs"
This command creates a new service named "TestService".
-------------------------- EXAMPLE 2 --------------------------
PS C:\>new-service -name TestService -binaryPathName "C:\WINDOWS\System32\svchost.exe -k netsvcs" -dependson NetLogon -displayName "Test Service" -StartupType Manual -Description "This is a test service."
This command creates a new service named "TestService". It uses the parameters of the New-Service cmdlet to specify a description, startup type, and display name for the new service.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-wmiobject win32_service -filter "name='testservice'"
ExitCode : 0
Name : testservice
ProcessId : 0
StartMode : Auto
State : Stopped
Status : OK
This command uses the Get-WmiObject cmdlet to get the Win32_Service object for the new service. This object includes the start mode and the service description.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>sc.exe delete TestService
- or -
PS C:\>(get-wmiobject win32_service -filter "name='TestService'").delete()
This example shows two ways to delete the TestService service. The first command uses the delete option of Sc.exe. The second command uses the Delete method of the Win32_Service objects that the Get-WmiObject cmdlet returns.
###RELATED LINKS Online Version: Get-Service Restart-Service Resume-Service Set-Service Start-Service Stop-Service Suspend-Service ##New-WebServiceProxy
###SYNOPSIS Creates a Web service proxy object that lets you use and manage the Web service in Windows PowerShell.
###SYNTAX TODO
###DESCRIPTION The New-WebServiceProxy cmdlet lets you use a Web service in Windows PowerShell. The cmdlet connects to a Web service and creates a Web service proxy object in Windows PowerShell. You can use the proxy object to manage the Web service. A Web service is an XML-based program that exchanges data over a network, particularly over the Internet. The Microsoft .NET Framework provides Web service proxy objects that represent the Web service as a .NET Framework object.
###PARAMETERS
####Class [<String>]
Specifies a name for the proxy class that the cmdlet creates for the Web service. The value of this parameter is used with the Namespace parameter to provide a fully qualified name for the class. The default value is generated from the URI.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. This is an alternative to using the UseDefaultCredential parameter. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
####Namespace [<String>]
Specifies a namespace for the new class. The value of this parameter is used with the value of the Class parameter to generate a fully qualified name for the class. The default value is Microsoft.PowerShell.Commands.NewWebserviceProxy.AutogeneratedTypes plus a type that is generated from the URI. You can set the value of the Namespace parameter so that you can access multiple Web services with the same name.
####Uri <Uri>
Specifies the URI of the Web service. Enter a URI or the path and file name of a file that contains a service description. The URI must refer to an .asmx page or to a page that returns a service description. To return a service description of a Web service that was created by using ASP.NET, append "?WSDL" to the URL of the Web service (for example, http://www.contoso.com/MyWebService.asmx?WSDL).
####UseDefaultCredential [<SwitchParameter>]
Sets the UseDefaultCredential property in the resulting proxy object to True. This is an alternative to using the Credential parameter.
###INPUTS ####None This cmdlet does not take input from the pipeline.
###OUTPUTS ####A Web service proxy object The namespace and class of the object are determined by the parameters of the command. The default is generated from the input Uniform Resource Identifier (URI).
###NOTES ####A Web service proxy object New-WebServiceProxy uses the System.Net.WebClient class to load the specified Web service.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>$zip = New-WebServiceProxy -Uri http://www.webservicex.net/uszip.asmx?WSDL
This command uses the New-WebServiceProxy command to create a .NET Framework proxy of the US Zip Web service in Windows PowerShell.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>$URI = "http://www.webservicex.net/uszip.asmx?WSDL"
PS C:\>$zip = New-WebServiceProxy -Uri $URI -Namespace WebServiceProxy -Class USZip
This command uses the New-WebServiceProxy cmdlet to create a .NET Framework proxy of the US Zip Web service. The first command stores the URI of the Web service in the $URI variable. The second command creates the Web service proxy. The command uses the URI parameter to specify the URI and the Namespace and Class parameters to specify the namespace and class of the object.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$zip | get-member -type method
TypeName: WebServiceProxy.USZip
Name MemberType Definition
---- ---------- ----------
Abort Method System.Void Abort(
BeginGetInfoByAreaCode Method System.IAsyncResul
BeginGetInfoByCity Method System.IAsyncResul
BeginGetInfoByState Method System.IAsyncResul
BeginGetInfoByZIP Method System.IAsyncResul
CreateObjRef Method System.Runtime.Rem
Discover Method System.Void Discov
Dispose Method System.Void Dispos
EndGetInfoByAreaCode Method System.Xml.XmlNode
EndGetInfoByCity Method System.Xml.XmlNode
EndGetInfoByState Method System.Xml.XmlNode
EndGetInfoByZIP Method System.Xml.XmlNode
Equals Method System.Boolean Equ
GetHashCode Method System.Int32 GetHa
GetInfoByAreaCode Method System.Xml.XmlNode
GetInfoByCity Method System.Xml.XmlNode
GetInfoByState Method System.Xml.XmlNode
GetInfoByZIP Method System.Xml.XmlNode
GetLifetimeService Method System.Object GetL
GetType Method System.Type GetTyp
InitializeLifetimeService Method System.Object Init
ToString Method System.String ToSt
This command uses the Get-Member cmdlet to display the methods of the Web service proxy object in the $zip variable. We will use these methods in the following example. Notice that the TypeName of the proxy object, WebServiceProxy, reflects the namespace and class names that were specified in the previous example. -------------------------- EXAMPLE 4 --------------------------
PS C:\>$zip.getinfobyzip(20500).table
CITY : Washington
STATE : DC
ZIP : 20500
AREA_CODE : 202
TIME_ZONE : E
This command uses the Web service proxy stored in the Zip variable. The command uses the GetInfoByZip method of the proxy and its Table property.
###RELATED LINKS Online Version: New-Service ##Pop-Location
###SYNOPSIS Changes the current location to the location most recently pushed onto the stack. You can pop the location from the default stack or from a stack that you create by using the Push-Location cmdlet.
###SYNTAX TODO
###DESCRIPTION The Pop-Location cmdlet changes the current location to the location most recently pushed onto the stack by using the Push-Location cmdlet. You can pop a location from the default stack or from a stack that you create by using a Push-Location command.
###PARAMETERS
####PassThru [<SwitchParameter>]
Passes an object representing the location to the pipeline. By default, this cmdlet does not generate any output.
####StackName [<String>]
Specifies the location stack from which the location is popped. Enter a location stack name. Without this parameter, Pop-Location pops a location from the current location stack. By default, the current location stack is the unnamed default location stack that Windows PowerShell creates. To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. NOTE: Pop-Location cannot pop a location from the unnamed default stack unless it is the current location stack.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe input to Pop-Location.
###OUTPUTS ####None or System.Management.Automation.PathInfo When you use the PassThru parameter, Pop-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PathInfo A "stack" is a last-in, first-out list in which only the most recently added item is accessible. You add items to a stack in the order that you use them, and then retrieve them for use in the reverse order. Windows PowerShell lets you store provider locations in location stacks. Windows PowerShell creates an unnamed default location stack and you can create multiple named location stacks. If you do not specify a stack name, Windows PowerShell uses the current location stack. By default, the unnamed default location is the current location stack, but you can use the Set-Location cmdlet to change the current location stack. To manage location stacks, use the Windows PowerShell Location cmdlets, as follows. -- To add a location to a location stack, use the Push-Location cmdlet. -- To get a location from a location stack, use the Pop-Location cmdlet. -- To display the locations in the current location stack, use the Stack parameter of the Get-Location cmdlet. To display the locations in a named location stack, use the StackName parameter of the Get-Location cmdlet. -- To create a new location stack, use the StackName parameter of the Push-Location cmdlet. If you specify a stack that does not exist, Push-Location creates the stack. -- To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. The unnamed default location stack is fully accessible only when it is the current location stack. If you make a named location stack the current location stack, you cannot no longer use Push-Location or Pop-Location cmdlets add or get items from the default stack or use Get-Location command to display the locations in the unnamed stack. To make the unnamed stack the current stack, use the StackName parameter of the Set-Location cmdlet with a value of $null or an empty string (""). You can also refer to Pop-Location by its built-in alias, "popd". For more information, see about_Aliases. The Pop-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>pop-location
This command changes your location to the location most recently added to the current stack.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>pop-location -stackname Stack2
This command changes your location to the location most recently added to the Stack2 location stack. For more information about location stacks, see the Notes.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>pushd HKLM:\Software\Microsoft\PowerShell
pushd Cert:\LocalMachine\TrustedPublisher
popd
popd
PS C:\>push-location HKLM:\Software\Microsoft\PowerShell
PS HKLM:\Software\Microsoft\PowerShell> push-location Cert:\LocalMachine\TrustedPublisher
PS cert:\LocalMachine\TrustedPublisher> popd
PS HKLM:\Software\Microsoft\PowerShell> popd
PS C:\ps-test>
These commands use the Push-Location and Pop-Location cmdlets to move between locations supported by different Windows PowerShell providers. The commands use the "pushd" alias for Push-Location and the "popd" alias for Pop-Location. The first command pushes the current file system location onto the stack and moves to the HKLM drive supported by the Windows PowerShell Registry provider. The second command pushes the registry location onto the stack and moves to a location supported by the Windows PowerShell certificate provider. The last two commands pop those locations off the stack. The first "popd" command returns to the Registry drive, and the second command returns to the file system drive.
###RELATED LINKS Online Version: Get-Location Push-Location Set-Location about_Providers ##Push-Location
###SYNOPSIS Adds the current location to the top of a location stack.
###SYNTAX TODO
###DESCRIPTION The Push-Location cmdlet adds ("pushes") the current location onto a location stack. If you specify a path, Push-Location pushes the current location onto a location stack and then changes the current location to the location specified by the path. You can use the Pop-Location cmdlet to get locations from the location stack. By default, the Push-Location cmdlet pushes the current location onto the current location stack, but you can use the StackName parameter to specify an alternate location stack. If the stack does not exist, Push-Location creates it. For more information about location stacks, see the Notes.
###PARAMETERS
####LiteralPath [<String>]
Specifies the path to the new location. Unlike the Path parameter, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Passes an object representing the location to the pipeline. By default, this cmdlet does not generate any output.
####Path [<String>]
Changes your location to the location specified by this path after it adds (pushes) the current location onto the top of the stack. Enter a path to any location whose provider supports this cmdlet. Wildcards are permitted. The parameter name ("Path") is optional.
####StackName [<String>]
Specifies the location stack to which the current location is added. Enter a location stack name. If the stack does not exist, Push-Location creates it. Without this parameter, Push-Location adds the location to the current location stack. By default, the current location stack is the unnamed default location stack that Windows PowerShell creates. To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. For more information about location stacks, see the Notes. NOTE: Push-Location cannot add a location to the unnamed default stack unless it is the current location stack.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path (but not a literal path) to Push-Location.
###OUTPUTS ####None or System.Management.Automation.PathInfo When you use the PassThru parameter, Push-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PathInfo A "stack" is a last-in, first-out list in which only the most recently added item is accessible. You add items to a stack in the order that you use them, and then retrieve them for use in the reverse order. Windows PowerShell lets you store provider locations in location stacks. Windows PowerShell creates an unnamed default location stack and you can create multiple named location stacks. If you do not specify a stack name, Windows PowerShell uses the current location stack. By default, the unnamed default location is the current location stack, but you can use the Set-Location cmdlet to change the current location stack. To manage location stacks, use the Windows PowerShell Location cmdlets, as follows. -- To add a location to a location stack, use the Push-Location cmdlet. -- To get a location from a location stack, use the Pop-Location cmdlet. -- To display the locations in the current location stack, use the Stack parameter of the Get-Location cmdlet. To display the locations in a named location stack, use the StackName parameter of the Get-Location cmdlet. -- To create a new location stack, use the StackName parameter of the Push-Location cmdlet. If you specify a stack that does not exist, Push-Location creates the stack. -- To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. The unnamed default location stack is fully accessible only when it is the current location stack. If you make a named location stack the current location stack, you cannot no longer use Push-Location or Pop-Location cmdlets add or get items from the default stack or use Get-Location command to display the locations in the unnamed stack. To make the unnamed stack the current stack, use the StackName parameter of the Set-Location cmdlet with a value of $null or an empty string (""). You can also refer to Push-Location by its built-in alias, "pushd". For more information, see about_Aliases. The Push-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>push-location C:\Windows
This command pushes the current location onto the default location stack and then changes the location to C:\Windows.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>push-location HKLM:\Software\Policies -stackname RegFunction
This command pushes the current location onto the RegFunction stack and changes the current location to the HKLM:\Software\Policies location. You can use the Location cmdlets in any Windows PowerShell drive (PSDrive).
-------------------------- EXAMPLE 3 --------------------------
PS C:\>push-location
This command pushes the current location onto the default stack. It does not change the location.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>push-location ~ -stackname Stack2
PS C:\Users\User01> pop-location -stackname Stack2
PS C:\>
These commands show how to create and use a named location stack. The first command pushes the current location onto a new stack named Stack2, and then changes the current location to the home directory (%USERPROFILE%), which is represented in the command by the tilde symbol (~) or $home. If Stack2 does not already exist in the session, Push-Location creates it. The second command uses the Pop-Location cmdlet to pop the original location (PS C:>) from the Stack2 stack. Without the StackName parameter, Pop-Location would pop the location from the unnamed default stack. For more information about location stacks, see the Notes.
###RELATED LINKS Online Version: Get-Location Pop-Location Set-Location about_Providers ##Register-WmiEvent
###SYNOPSIS Subscribes to a Windows Management Instrumentation (WMI) event.
###SYNTAX TODO
###DESCRIPTION The Register-WmiEvent cmdlet subscribes to WMI events on the local computer or on a remote computer. When the subscribed WMI event is raised, it is added to the event queue in your local session even if the event occurs on a remote computer. To get events in the event queue, use the Get-Event cmdlet. You can use the parameters of Register-WmiEvent to subscribe to events on remote computers and to specify the property values of the events that can help you to identify the event in the queue. You can also use the Action parameter to specify actions to take when a subscribed event is raised. When you subscribe to an event, an event subscriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session. New CIM cmdlets, introduced Windows PowerShell 3.0, perform the same tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) standards and with the Common Information Model (CIM) standard, which enables the cmdlets to use the same techniques to manage Windows computers and those running other operating systems. Instead of using Register-WmiEvent, consider using the Register-CimIndicationEvent cmdlet.
###PARAMETERS
####Action [<ScriptBlock>]
Specifies commands that handle the events. The commands in the Action parameter run when an event is raised instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block. The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables. When you specify an action, Register-WmiEvent returns an event job object that represents that action. You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage the event job.
####Class <String>
Specifies the event to which you are subscribing. Enter the WMI class that generates the events. A Class or Query parameter is required in every command.
####ComputerName [<String>]
Runs the command on the specified computer. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of the computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one from the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
####Forward [<SwitchParameter>]
Sends events for this subscription to the session on the local computer. Use this parameter when you are registering for events on a remote computer or in a remote session.
####MaxTriggerCount [<Int32>]
Specifies the maximum number of times that an event is raised before users who are registered as event subscribers are automatically unsubscribed. The default value, zero (0), means that there is no maximum. Users are not automatically unsubscribed, regardless of the number of times the event is raised.
####MessageData [<PSObject>]
Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.
####Namespace [<String>]
Specifies the namespace of the WMI class.
####Query <String>
Specifies a query in WMI Query Language (WQL) that identifies the WMI event class, such as "select * from __InstanceDeletionEvent".
####SourceIdentifier [<String>]
Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that Windows PowerShell assigns. The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription.
####SupportEvent [<SwitchParameter>]
Hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently. To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.
####Timeout [<Int64>]
Determines how long Windows PowerShell waits for this command to complete. The default value, 0 (zero), means that there is no time-out, and it causes Windows PowerShell to wait indefinitely.
###INPUTS ####None You cannot pipe objects to Register-WmiEvent.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None To use this cmdlet in Windows Vista or a later version of Windows, start Windows PowerShell with the "Run as administrator" option. Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"
This command subscribes to the events generated by the Win32_ProcessStartTrace class. This class raises an event whenever a process starts.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500
This command uses a query to subscribe to Win32_process instance creation events.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }
PS C:\>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
1 ProcessStarted NotStarted False get-history | where {...
This example shows how to use an action to respond to an event. In this case, when a process starts, any Start-Process commands in the current session are written to an XML file. When you use the Action parameter, Register-WmiEvent returns a background job that represents the event action. You can use the Job cmdlets, such as Get-Job and Receive-Job, to manage the event job. For more information, see about_Jobs.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01
PS C:\>get-event -sourceIdentifier "Start"
This example registers for events on the Server01 remote computer. WMI returns the events to the local computer and stores them in the event queue in the current session. To retrieve the events, run a local Get-Event command.
###RELATED LINKS Online Version: Get-Event New-Event Register-EngineEvent Register-ObjectEvent Remove-Event Unregister-Event Wait-Event ##Remove-Computer
###SYNOPSIS Removes the local computer from its domain.
###SYNTAX TODO
###DESCRIPTION The Remove-Computer cmdlet removes the local computer and remote computers from their current domains. When you remove a computer from a domain, Remove-Computer also disables the computer's domain account. You must provide explicit credentials to unjoin the computer from its domain, even when they are the credentials of the current user, and you must restart the computer to make the change effective. Also, when you remove a computer from a domain, you must move it to a workgroup. Use the WorkgroupName parameter to specify the workgroup. To move a computer from a workgroup to a domain, from one workgroup to another, or from one domain to another, use the Add-Computer cmdlet. To get the results of the command, use the Verbose and PassThru parameters. To suppress the user prompt, use the Force parameter. Remove-Computer removes the local computer and remote computers from domains. It includes credential parameters that specify alternate credentials for connecting to remote computers, and unjoining from a domain, a Restart parameter for restarting the affected computers, and a WorkgroupName parameter for specifying the name of the workgroup to which computers are added.
###PARAMETERS
####ComputerName [<String[]>]
Specifies the computers to be removed from their domains. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of the remote computers. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Remove-Computer even if your computer is not configured to run remote commands. This parameter is introduced in Windows PowerShell 3.0.
####Force [<SwitchParameter>]
Suppresses the user prompt. By default, Remove-Computer prompts you for confirmation before removing each computer.
####LocalCredential [<PSCredential>]
Specifies a user account that has permission to connect to the computers that are specified by the ComputerName parameter. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. To specify a user account that has permission to remove the computer from its current domain, use the UnjoinDomainCredential parameter. This parameter is introduced in Windows PowerShell 3.0.
####PassThru [<SwitchParameter>]
Returns the results of the command. Otherwise, this cmdlet does not generate any output.
####Restart [<SwitchParameter>]
Restarts the computers that were removed after the removal is complete. A restart is often required to make the change effective. This parameter is introduced in Windows PowerShell 3.0.
####UnjoinDomainCredential [<PSCredential>]
Specifies a user account that has permission to remove the computers from their current domains. Explicit credentials, as provided by this parameter, are required to remove remote computers from a domain, even when the value is the credentials of the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. You can refer to this parameter by its name, UnjoinDomainCredential, or its alias, Credential. To specify a user account that has permission to connect to the remote computers, use the LocalCredential parameter. This parameter is introduced in Windows PowerShell 3.0.
####WorkgroupName [<String>]
Specifies the name of a workgroup to which the computers are added when they are removed from their domains. The default value is "WORKGROUP". When you remove a computer from a domain, you must add it to a workgroup. This parameter is introduced in Windows PowerShell 3.0.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.String You can pipe computer names to the Remove-Computer cmdlet.
###OUTPUTS ####Microsoft.PowerShell.Commands.ComputerChangeInfo When you use the PassThru parameter, Remove-Computer returns a ComputerChangeInfo object. Otherwise, this cmdlet does not generate any output.
###NOTES ####Microsoft.PowerShell.Commands.ComputerChangeInfo This cmdlet does not remove computers from workgroups.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Remove-Computer -UnjoinDomaincredential Domain01\Admin01 -Passthru -Verbose -Restart
This command removes the local computer from the domain to which it is joined. The command uses the UnjoinDomainCredential parameter to supply the credentials of a domain administrator. It uses the PassThru parameter and the Verbose common parameter to display information about the success or failure of the command and the Restart parameter restart the computer, which is required to complete the remove operation. Because the command does not specify a workgroup name, the local computer is moved to the "WORKGROUP" workgroup after it is removed from its domain. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Remove-Computer -ComputerName (Get-Content OldServers.txt) -LocalCredential Domain01\Admin01 -UnJoinDomainCredential Domain01\Admin01 -WorkgroupName Legacy -Force -Restart
This command removes all of the computers that are listed in the OldServers.txt file from their domains and places them in the Legacy workgroup. The command uses the LocalCredential parameter to supply the credentials of a user who has permission to connect to remote computers and the UnjoinDomainCredential parameter to supply the credentials of a user who has permission to remove the computers from their domains. It uses the Force parameter to suppress the confirmation prompts for each computer and the Restart parameter to restart each of the computers after it is removed from its domain. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Remove-Computer -ComputerName Server01, localhost -UnjoinDomainCredential Domain01\Admin01 -WorkgroupName Local -Restart -Force
This command removes the Server01 remote computer and the local computer from their domains and adds them to the Local workgroup. It uses the Force parameter to suppress the confirmation prompt for each computer and the Restart parameter to restart the computers to make the change effective.
###RELATED LINKS Online Version: Add-Computer Checkpoint-Computer Remove-Computer Rename-Computer Restart-Computer Restore-Computer Stop-Computer Test-Connection ##Remove-EventLog
###SYNOPSIS Deletes an event log or unregisters an event source.
###SYNTAX TODO
###DESCRIPTION The Remove-EventLog cmdlet deletes an event log file from a local or remote computer and unregisters all of its event sources for the log. You can also use this cmdlet to unregister event sources without deleting any event logs. The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent. CAUTION: This cmdlet can delete operating system event logs, which might result in application failures and unexpected system behavior.
###PARAMETERS
####ComputerName [<String[]>]
Specifies a remote computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Remove-EventLog even if your computer is not configured to run remote commands.
####LogName <String[]>
Specifies the event logs. Enter the log name (the value of the Log property; not the LogDisplayName) of one or more event logs , separated by commas. Wildcard characters are not permitted. This parameter is required.
####Source [<String[]>]
Unregisters the specified event sources. Enter the source names (not the executable name), separated by commas.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not return any output.
###NOTES ####None To use Remove-EventLog on Windows Vista and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. If you remove an event log and then re-create the log, you will not be able to register the same event sources. Applications that used the events sources to write entries to the original log will not be able to write to the new log. When you unregister an event source for a particular log, the event source might be prevented from writing entries in other event logs.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>remove-eventlog -logname MyLog
This command deletes the MyLog event log from the local computer and unregisters its event sources.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>remove-eventlog -logname MyLog, TestLog -computername Server01, Server02, localhost
This command deletes the MyLog and TestLog event logs from the local computer ("localhost") and the Server01 and Server02 remote computers. The command also unregisters the event sources for these logs.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>remove-eventlog -source MyApp
This command deletes the MyApp event source from the logs on the local computer. When the command completes, the MyApp program cannot write to any event logs.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-eventlog -list
Max(K) Retain OverflowAction Entries Log
------ ------ -------------- ------- ---
15,168 0 OverwriteAsNeeded 22,923 Application
15,168 0 OverwriteAsNeeded 53 DFS Replication
15,168 7 OverwriteOlder 0 Hardware Events
512 7 OverwriteOlder 0 Internet Explorer
20,480 0 OverwriteAsNeeded 0 Key Management Service
30,016 0 OverwriteAsNeeded 50,060 Security
15,168 0 OverwriteAsNeeded 27,592 System
15,360 0 OverwriteAsNeeded 18,355 Windows PowerShell
15,168 7 OverwriteAsNeeded 12 ZapLog
PS C:\>remove-eventlog -logname ZapLog
PS C:\>get-eventlog -list
Max(K) Retain OverflowAction Entries Log
------ ------ -------------- ------- ---
15,168 0 OverwriteAsNeeded 22,923 Application
15,168 0 OverwriteAsNeeded 53 DFS Replication
15,168 7 OverwriteOlder 0 Hardware Events
512 7 OverwriteOlder 0 Internet Explorer
20,480 0 OverwriteAsNeeded 0 Key Management Service
30,016 0 OverwriteAsNeeded 50,060 Security
15,168 0 OverwriteAsNeeded 27,592 System
15,360 0 OverwriteAsNeeded 18,355 Windows PowerShell
These commands show how to list the event logs on a computer and verify that a Remove-EventLog command was successful. The first command lists the event logs on the local computer. The second command deletes the ZapLog event log. The third command lists the event logs again. The ZapLog event log no longer appears in the list.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>get-wmiobject win32_nteventlogfile -filter "logfilename='TestLog'" | foreach {$_.sources}
MyApp
TestApp
PS C:\>remove-eventlog -source MyApp
PS C:\>get-wmiobject win32_nteventlogfile -filter "logfilename='TestLog'"} | foreach {$_.sources}
TestApp
These commands use the Get-WmiObject cmdlet to list the event sources on the local computer. You can these commands to verify the success of a command or to delete an event source. The first command gets the event sources of the TestLog event log on the local computer. MyApp is one of the sources. The second command uses the Source parameter of Remove-EventLog to delete the MyApp event source. The third command is identical to the first. It shows that the MyApp event source was deleted.
###RELATED LINKS Online Version: Clear-EventLog Get-EventLog Limit-EventLog New-EventLog Remove-EventLog Show-EventLog Write-EventLog ##Remove-Item
###SYNOPSIS Deletes the specified items.
###SYNTAX TODO
###DESCRIPTION The Remove-Item cmdlet deletes one or more items. Because it is supported by many providers, it can delete many different types of items, including files, directories, registry keys, variables, aliases, and functions.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to remove items that cannot otherwise be changed, such as hidden or read-only files or read-only aliases or variables. The cmdlet cannot remove constant aliases or variables. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Deletes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies a path to the items being removed. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies a path to the items being removed. Wildcards are permitted. The parameter name ("-Path") is optional.
####Recurse [<SwitchParameter>]
Deletes the items in the specified locations and in all child items of the locations. When it is used with the Include parameter, the Recurse parameter might not delete all child directories or all child items. This is a known issue; as a workaround, try piping results of the Get-ChildItem -Recurse cmdlet into the Remove-Item cmdlet, as described in Example 4 in this topic.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path (but not a literal path) to Remove-Item.
###OUTPUTS ####None This cmdlet does not return any output.
###NOTES ####None You can also refer to Remove-Item by any of its built-in aliases, "del", "erase", "rmdir", "rd", "ri", or "rm". For more information, see about_Aliases. The Remove-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>remove-item C:\Test\*.*
This command deletes all of the files with names that include a dot (.) from the C:\Test directory. Because the command specifies a dot, the command does not delete directories or files with no file name extension. -------------------------- EXAMPLE 2 --------------------------
PS C:\>remove-item * -include *.doc -exclude *1*
This command deletes from the current directory all files with a .doc file name extension and a name that does not include "1". It uses the wildcard character (*) to specify the contents of the current directory. It uses the Include and Exclude parameters to specify the files to delete. -------------------------- EXAMPLE 3 --------------------------
PS C:\>remove-item -path C:\Test\hidden-RO-file.txt -force
This command deletes a file that is both hidden and read-only. It uses the Path parameter to specify the file. It uses the Force parameter to give permission to delete it. Without Force, you cannot delete read-only or hidden files. -------------------------- EXAMPLE 4 --------------------------
PS C:\>get-childitem * -include *.csv -recurse | remove-item
This command deletes all of the CSV files in the current directory and all subdirectories recursively. Because the Recurse parameter in the Remove-Item cmdlet has a known issue (it might not delete all child directories or files, especially if the Include parameter is added to the command), the command in this example uses the Get-ChildItem cmdlet to get the desired files, and then uses the pipeline operator to pass them to the Remove-Item cmdlet. In the Get-ChildItem command, the Path parameter has a value of *, which represents the contents of the current directory. It uses the Include parameter to specify the CSV file type, and it uses the Recurse parameter to make the retrieval recursive. If you try to specify the file type in the path, such as "-path *.csv", the cmdlet interprets the subject of the search to be a file that has no child items, and Recurse fails. -------------------------- EXAMPLE 5 --------------------------
PS C:\>remove-item hklm:\software\mycompany\OldApp -recurse
This command deletes the OldApp registry key and all of its subkeys and values. It uses the Remove-Item cmdlet to remove the key. The path is specified, but the optional parameter name (Path) is omitted. The Recurse parameter deletes all of the contents of the OldApp key recursively. If the key contains subkeys and you omit the Recurse parameter, you are prompted to confirm that you want to delete the contents of the key.
###RELATED LINKS Online Version: Clear-Item Copy-Item Get-Item Invoke-Item Move-Item New-Item Remove-ItemProperty Rename-Item Set-Item about_Providers ##Remove-ItemProperty
###SYNOPSIS Deletes the property and its value from an item.
###SYNTAX TODO
###DESCRIPTION The Remove-ItemProperty cmdlet deletes a property and its value from an item. You can use it to delete registry values and the data that they store.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to remove a property of an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_Providers.
####Include [<String[]>]
Deletes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String[]>
Specifies the names of the properties to be retrieved.
####Path <String[]>
Specifies the path to the item whose properties are being removed. Wildcards are permitted.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path (but not a literal path) to Remove-ItemProperty.
###OUTPUTS ####None This cmdlet does not return any output.
###NOTES ####None You can also refer to Remove-ItemProperty by its built-in alias, "rp". For more information, see about_Alias. In the Windows PowerShell Registry provider, registry values are considered to be properties of a registry key or subkey. You can use the ItemProperty cmdlets to manage these values. The Remove-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>remove-itemproperty -path HKLM:\Software\SmpApplication -name SmpProperty
This command deletes the SmpProperty registry value, and its data, from the SmpApplication subkey of the HKEY_LOCAL_MACHINE\Software registry key. Because the command is issued from a file system drive (PS C:>), it includes the fully qualified path to the SmpApplication subkey, including the drive, HKLM:, and the Software key. It uses the Name parameter to identify the registry value that is being deleted.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>set-location HKCU:\Software\MyCompany\MyApp
PS HKCU:\Software\MyCompany\MyApp> remove-itemproperty -path . -Name Options -confirm
These commands delete the Options registry value, and its data, from the MyApp subkey of HKEY_CURRENT_USER\Software\MyCompany. The first command uses the Set-Location cmdlet to change the current location to the HKEY_CURRENT_USER drive (HKCU:) and the Software\MyCompany\MyApp subkey. The second command uses the Remove-Item cmdlet to remove the Options registry value, and its data, from the MyApp subkey. Because the Path parameter is required, the command uses a dot (.) to indicate the current location. It uses the Name parameter to specify which registry value to delete. It uses the Confirm parameter to request a user prompt before deleting the value.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-item -path HKLM:\Software\MyCompany | remove-itemproperty -name NoOfEmployees
This command deletes the NoOfEmployees registry value, and its data, from the HKLM\Software\MyCompany registry key. The command uses the Get-Item cmdlet to get an item that represents the registry key. It uses a pipeline operator (|) to send the object to the Remove-ItemProperty cmdlet. Then, it uses the Name parameter of Remove-ItemProperty to specify the name of the registry value.
###RELATED LINKS Online Version: Clear-ItemProperty Copy-ItemProperty Get-ItemProperty Move-ItemProperty New-ItemProperty Remove-Item Rename-ItemProperty Set-ItemProperty about_Providers ##Remove-PSDrive
###SYNOPSIS Deletes temporary Windows PowerShell drives and disconnects mapped network drives.
###SYNTAX TODO
###DESCRIPTION The Remove-PSDrive cmdlet deletes temporary Windows PowerShell drives that were created by using the New-PSDrive cmdlet. Beginning in Windows PowerShell 3.0, Remove-PSDrive also disconnects mapped network drives, including, but not limited to, drives created by using the Persist parameter of New-PSDrive. Remove-PSDrive cannot delete Windows physical or logical drives. Beginning in Windows PowerShell 3.0, when an external drive is connected to the computer, Windows PowerShell automatically adds a PSDrive to the file system that represents the new drive. You do not need to restart Windows PowerShell. Similarly, when an external drive is disconnected from the computer, Windows PowerShell automatically deletes the PSDrive that represents the removed drive.
###PARAMETERS
####Force [<SwitchParameter>]
Removes the current Windows PowerShell drive.
####LiteralName <String[]>
Specifies the name of the drive. The value of LiteralName is used exactly as typed. No characters are interpreted as wildcards. If the name includes escape characters, enclose it in single quotation marks ('). Single quotation marks instruct Windows PowerShell not to interpret any characters as escape sequences.
####Name <String[]>
Specifies the names of the drives to remove. Do not type a colon (:) after the drive name.
####PSProvider [<String[]>]
Removes and disconnects all of the drives associated with the specified Windows PowerShell provider.
####Scope [<String>]
Accepts an index that identifies the scope from which the drive is being removed.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.Management.Automation.PSDriveInfo You can pipe a drive object, such as one from the Get-PSDrive cmdlet, to the Remove-PSDrive cmdlet.
###OUTPUTS ####None This cmdlet does not return any output.
###NOTES ####None The Remove-PSDrive cmdlet is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250).
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Remove-PSDrive -Name smp
This command removes a temporary file system drive named "smp". -------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-PSDrive X, S | Remove-PSDrive
This command disconnects the X: mapped network drive that was created in File Explorer and the S: mapped network drive that was created by using the Persist parameter of the New-PSDrive cmdlet. The command uses the Get-PSDrive cmdlet to get the drives and the Remove-PSDrive cmdlet to disconnect them.
###RELATED LINKS Online Version: Get-PSDrive New-PSDrive about_Providers ##Remove-WmiObject
###SYNOPSIS Deletes an instance of an existing Windows Management Instrumentation (WMI) class.
###SYNTAX TODO
###DESCRIPTION The Remove-WmiObject cmdlet deletes an instance of an existing WMI class.
###PARAMETERS
####AsJob [<SwitchParameter>]
Runs the command as a background job. Use this parameter to run commands that take a long time to finish. {New CIM cmdlets, introduced Windows PowerShell 3.0, perform the same tasks as the WMI cmdl... When you use the AsJob parameter, the command returns an object that represents the background job and then displays the command prompt. You can continue to work in the session while the job finishes. If Remove-WmiObject is used against a remote computer, the job is created on the local computer, and the results from remote computers are automatically returned to the local computer. To manage the job, use the cmdlets that contain the Job noun (the Job cmdlets). To get the job results, use the Receive-Job cmdlet. Note: To use this parameter with remote computers, the local and remote computers must be configured for remoting. Start Windows PowerShell by using the "Run as administrator" option. For more information, see about_Remote_Requirements. For more information about Windows PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
####Authentication [<AuthenticationLevel>]
Specifies the authentication level to be used with the WMI connection. Valid values are: -1: Unchanged 0: Default 1: None (No authentication in performed.) 2: Connect (Authentication is performed only when the client establishes a relationship with the application.) 3: Call (Authentication is performed only at the beginning of each call when the application receives the request.) 4: Packet (Authentication is performed on all the data that is received from the client.) 5: PacketIntegrity (All the data that is transferred between the client and the application is authenticated and verified.) 6: PacketPrivacy (The properties of the other authentication levels are used, and all the data is encrypted.)
####Authority [<String>]
Specifies the authority to use to authenticate the WMI connection. You can specify standard NTLM or Kerberos authentication. To use NTLM, set the authority setting to "ntlmdomain:", where identifies a valid NTLM domain name. To use Kerberos, specify "kerberos:<ServerName>". You cannot include the authority setting when you connect to the local computer.
####Class <String>
Specifies the name of a WMI class that you want to delete.
####ComputerName [<String[]>]
Runs the command on the specified computers. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more computers. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01", "Domain01\User01", or "[email protected]". Or, enter a PSCredential object, such as an object that is returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.
####EnableAllPrivileges [<SwitchParameter>]
Enables all the privileges of the current user before the command makes the WMI call.
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use. Valid values are: 0: Default (Reads the local registry for the default impersonation level, which is usually set to "3: Impersonate".) 1: Anonymous (Hides the credentials of the caller.) 2: Identify (Allows objects to query the credentials of the caller.) 3: Impersonate (Allows objects to use the credentials of the caller.) 4: Delegate (Allows objects to permit other objects to use the credentials of the caller.)
####InputObject <ManagementObject>
Specifies a ManagementObject object to use as input. When this parameter is used, all other parameters are ignored.
####Locale [<String>]
Specifies the preferred locale for WMI objects. The Locale parameter is specified as an array in the MS_ format in the preferred order.
####Namespace [<String>]
When used with the Class parameter, this parameter specifies the WMI repository namespace where the referenced WMI class is located.
####Path <String>
Specifies the WMI object path of a WMI class, or specifies the WMI object path of an instance of a WMI class to delete.
####ThrottleLimit [<Int32>]
Allows the user to specify a throttling value for the number of WMI operations that can be executed simultaneously. This parameter is used together with the AsJob parameter. The throttle limit applies only to the current command, not to the session or to the computer.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.Management.ManagementObject You can pipe a management object to Remove-WmiObject.
###OUTPUTS ####None or System.Management.Automation.RemotingJob When you use the AsJob parameter, this cmdlet returns a job object. Otherwise, it does not generate any output.
###NOTES ####None or System.Management.Automation.RemotingJob
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>notepad
PS C:\>$np = get-wmiobject -query "select * from win32_process where name='notepad.exe'"
PS C:\>$np | remove-wmiobject
This command closes all the instances of Notepad.exe. The first command starts an instance of Notepad. The second command uses the Get-WmiObject cmdlet to retrieve the instances of the Win32_Process that correspond to Notepad.exe and stores them in the $np variable. The third command passes the object in the $np variable to the Remove-WmiObject cmdlet, which deletes all the instances of Notepad.exe.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>$a = Get-WMIObject -query "Select * From Win32_Directory Where Name ='C:\\Test'"
PS C:\>$a | Remove-WMIObject
This command deletes the C:\Test directory. The first command uses the Get-WMIObject cmdlet to query for the C:\Test directory and then stores the object in the $a variable. The second command pipes the $a variable to the Remove-WMIObject, which deletes the directory.
###RELATED LINKS Online Version: Get-WSManInstance Invoke-WSManAction New-WSManInstance Remove-WSManInstance Get-WmiObject Invoke-WmiMethod Set-WmiInstance ##Rename-Computer
###SYNOPSIS Renames a computer.
###SYNTAX TODO
###DESCRIPTION The Rename-Computer cmdlet renames the local computer or a remote computer. It renames one computer in each command.
This cmdlet is introduced in Windows PowerShell 3.0.
###PARAMETERS
####ComputerName [<String>]
Renames the specified remote computer. The default is the local computer.
Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost".
This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Rename-Computer even if your computer is not configured to run remote commands.
####DomainCredential [<PSCredential>]
Specifies a user account that has permission to connect to the domain. Explicit credentials are required to rename a computer that is joined to a domain.
Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
To specify a user account that has permission to connect to the computer that is specified by the ComputerName parameter, use the LocalCredential parameter.
####Force [<SwitchParameter>]
Suppresses the user confirmation prompt. Without this parameter, Rename-Computer prompts you to confirm the action.
####LocalCredential [<PSCredential>]
Specifies a user account that has permission to connect to the computer specified by the ComputerName parameter. The default is the current user.
Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password
To specify a user account that has permission to connect to the domain, use the DomainCredential parameter.
####NewName <String>
Specifies a new name for the computer. This parameter is required. The name cannot include control characters, leading or trailing spaces, or any of the following characters: / \ [ ].
####PassThru [<SwitchParameter>]
Returns the results of the command. Otherwise, this cmdlet does not generate any output.
####Restart [<SwitchParameter>]
Restarts the computer that was renamed. A restart is often required to make the change effective.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None.
This cmdlet does not have parameters that take input by value. However, you can pipe the values of the ComputerName and NewName properties of objects to this cmdlet.
###OUTPUTS ####Microsoft.PowerShell.Commands.ComputerChangeInfo
When you use the PassThru parameter, Rename-Computer returns a ComputerChangeInfo object. Otherwise, it does not return any output.
###NOTES ####Microsoft.PowerShell.Commands.ComputerChangeInfo
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Rename-Computer -NewName Server044 -DomainCredential Domain01\Admin01 -Restart
This command renames the local computer to Server044 and then restarts it to make the change effective.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Rename-Computer -ComputerName Srv01 -NewName Server001 -LocalCredential Srv01\Admin01 -DomainCredential Domain01\Admin01 -Force -PassThru -Restart
This command renames the Srv01 computer to Server001 and then restarts it to make the change effective. It uses the LocalCredential parameter to supply the credentials of a user who has permission to connect to the local computer and the DomainCredential parameter to supply the credentials of a user who has permission to rename computers in the domain. It uses the Force parameter to suppress the confirmation prompt and the PassThru parameter to return the results of the command.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$a = Import-Csv ServerNames.csv -Header OldName, NewName
PS C:\>Foreach ( $Server in $a ) {Rename-Computer -ComputerName $Server.OldName -NewName $Server.NewName -DomainCredential Domain01\Admin01 -Force -Restart}
This command renames multiple computers in the domain. It uses a CSV file to specify the values for the current and new names of each computer. The CSV file contains a series of name pairs in "OldName, NewName" format with one name pair on each line of the file.
The first command uses the Import-Csv cmdlet to import the ServerNames.csv file into the $a variable. It uses the Header parameter to specify the column header names of each of the two columns. This creates a collection of custom objects in $a, each of which has an OldName and NewName property.
The second command runs the Rename-Computer cmdlet on each object in the $a variable. It specifies the old name (the value of the OldName property) for the value of the ComputerName parameter and the new name (the value of the NewName property) for the value of the NewName parameter. The command specifies domain credentials and uses the Force and Restart parameters to suppress all user prompts and restart each computer after it is renamed.
###RELATED LINKS Online Version: Add-Computer Remove-Computer Reset-ComputerMachinePassword Restart-Computer Stop-Computer ##Rename-Item
###SYNOPSIS Renames an item in a Windows PowerShell provider namespace.
###SYNTAX TODO
###DESCRIPTION The Rename-Item cmdlet changes the name of a specified item. This cmdlet does not affect the content of the item being renamed. You cannot use Rename-Item to move an item, such as by specifying a path along with the new name. To move and rename an item, use the Move-Item cmdlet.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Force [<SwitchParameter>]
Allows the cmdlet to rename items that cannot otherwise be changed, such as hidden or read-only files or read-only aliases or variables. The cmdlet cannot change constant aliases or variables. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####LiteralPath <String>
Specifies the path to the item to rename. Unlike the Path parameter, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####NewName <String>
Specifies the new name of the item. Enter only a name, not a path and name. If you enter a path that is different from the path that is specified in the Path parameter, Rename-Item generates an error. To rename and move an item, use the Move-Item cmdlet. You cannot use wildcard characters in the value of NewName. To specify a name for multiple files, use the Replace operator in a regular expression. For more information about the Replace operator, type "get-help about_comparison_operators". For a demonstration, see the examples.
####PassThru [<SwitchParameter>]
Passes an object representing the item to the pipeline. By default, this cmdlet does not generate any output.
####Path <String>
Specifies the path to the item to rename.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Rename-Item.
###OUTPUTS ####None or an object representing the renamed item. When you use the Passthru parameter, Rename-Item generates an object representing the renamed item. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or an object representing the renamed item. The Rename-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>rename-item -path c:\logfiles\daily_file.txt -newname monday_file.txt
This command renames the file daily_file.txt to monday_file.txt.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>rename-item -path project.txt -newname d:\archive\old-project.txt
Rename-Item : Cannot rename because the target specified represents a path or device name.
At line:1 char:12
+ rename-item <<<< -path project.txt -newname d:\archive\old-project.txt
+ CategoryInfo : InvalidArgument: (:) [Rename-Item], PSArgumentException
+ FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.RenameItemCommand
PS C:\>move-item -path project.txt -destination d:\archive\old-project.txt
# Command succeeds
This example shows that you cannot use the Rename-Item cmdlet to both rename and move an item. Specifically, you cannot supply a path for the value of the NewName parameter, unless the path is identical to the path specified in the Path parameter. Otherwise, only a new name is permitted. The first command uses the Rename-Item cmdlet to rename the project.txt file in the current directory to old-project.txt in the D:\Archive directory. The result is the error shown in the output. The second command shows the correct way to move and rename a file by using the Move-Item cmdlet. The Move-Item cmdlet lets you specify both a new path and a new name in the value of its Destination parameter.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>rename-item HKLM:\Software\MyCompany\Advertising -NewName Marketing
This command uses the Rename-Item cmdlet to rename a registry key from Advertising to Marketing. When the command is complete, the key is renamed, but the registry entries in the key are unchanged.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-childItem *.txt | rename-item -newname { $_.name -replace '\.txt','.log' }
This example shows how to use the Replace operator to rename multiple files, even though the NewName parameter does not accept wildcard characters. This command renames all of the .txt files in the current directory to .log. The command uses a Get-ChildItem cmdlet to get all of the files in the current directory that have a .txt file name extension. Then, it uses the pipeline operator (|) to send the resulting files to the Rename-Item cmdlet. In the Rename-Item command, the value of the NewName parameter is a script block that is executed before the value is submitted to the NewName parameter. In the script block, the $_ automatic variable represents each file object as it comes to the command through the pipeline. The command uses the dot format (.) to get the Name property of each file object. The Replace operator replaces the ".txt" file name extension of each file with ".log". Because the Replace operator works with regular expressions, the dot preceding "txt" is interpreted to match any character. To ensure that it matches only a dot (.), it is escaped with a backslash character (). The backslash character is not required in ".log" because it is a string, not a regular expression.
###RELATED LINKS Online Version: Clear-Item Copy-Item Get-Item Invoke-Item Move-Item New-Item Remove-Item Rename-ItemProperty Set-Item about_Providers ##Rename-ItemProperty
###SYNOPSIS Renames a property of an item.
###SYNTAX TODO
###DESCRIPTION The Rename-ItemProperty cmdlet changes the name of a specified item property. The value of the property is not changed. For example, you can use Rename-ItemProperty to change the name of a registry entry.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to rename a property of an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_Providers.
####Include [<String[]>]
Specifies only those items upon which the cmdlet will act, excluding all others.
####LiteralPath <String>
Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String>
Specifies the current name of the property to be renamed.
####NewName <String>
Specifies the new name for the property.
####PassThru [<SwitchParameter>]
Returns an object representing the item property. By default, this cmdlet does not generate any output.
####Path <String>
Specifies the path to the item to be renamed.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path (but not a literal path) to Rename-ItemProperty.
###OUTPUTS ####None or System.Management.Automation.PSCustomObject When you use the PassThru parameter, Rename-ItemProperty generates a PSCustomObject representing the renamed item property. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PSCustomObject The Remove-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>rename-itemproperty -path HKLM:\Software\SmpApplication -name config -newname oldconfig
This command renames the config registry entry contained in the HKEY_LOCAL_MACHINE\Software\SmpApplication key to oldconfig.
###RELATED LINKS Online Version: Clear-ItemProperty Copy-ItemProperty Get-ItemProperty Move-ItemProperty New-ItemProperty Remove-ItemProperty Rename-Item Set-ItemProperty about_Providers ##Reset-ComputerMachinePassword
###SYNOPSIS Resets the machine account password for the computer.
###SYNTAX TODO
###DESCRIPTION The Reset-ComputerMachinePassword cmdlet changes the machine account password that the computers use to authenticate to the domain controllers in the domain. You can use it to reset the password of the local computer.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission in the domain to reset the computer's machine password. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is introduced in Windows PowerShell 3.0.
####Server [<String>]
Specifies the name of a domain controller to use when setting the machine account password. This parameter is optional. If you omit this parameter, a domain controller is chosen to service the command.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Reset-ComputerMachinePassword
This command resets the machine password for the local computer. The command runs with the credentials of the current user. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Reset-ComputerMachinePassword -Server DC01 -Credential Domain01\Admin01
This command resets the machine password of the local computer using the DC01 domain controller. It uses the Credential parameter to specify a user account that has permission to reset a machine password in the domain. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Invoke-Command -ComputerName Server01 -ScriptBlock {Reset-ComputerMachinePassword}
This command uses theInvoke-Command cmdlet to run a Reset-ComputerMachinePassword command on the Server01 remote computer. For more information about remote commands in Windows PowerShell, see about_Remote and Invoke-Command.
###RELATED LINKS Online Version: ##Resolve-Path
###SYNOPSIS Resolves the wildcard characters in a path, and displays the path contents.
###SYNTAX TODO
###DESCRIPTION The Resolve-Path cmdlet interprets the wildcard characters in a path and displays the items and containers at the location specified by the path, such as the files and folders or registry keys and subkeys.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####LiteralPath <String[]>
Specifies the path to be resolved. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies the Windows PowerShell path to resolve. This parameter is required. You can also pipe a path string to Resolve-Path.
####Relative [<SwitchParameter>]
Returns a relative path.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Resolve-Path.
###OUTPUTS ####System.Management.Automation.PathInfo or System.String If you use the Relative parameter, Resolve-Path returns a string that contains the resolved path. Otherwise, it returns a PathInfo object.
###NOTES ####System.Management.Automation.PathInfo or System.String The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators. You can use the Path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers. The Resolve-Path cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>resolve-path ~
C:\Users\User01
This command resolves the path represented by the tilde character (~), which represents the home path of a file system drive, such as C:.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>resolve-path windows
C:\Windows
When run from the root of the C: drive, this command returns the path to the Windows directory in the C: drive.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>"C:\windows\*" | resolve-path
This command returns all of the directories in the C:\Windows directory. The command uses a pipeline operator (|) to send a path string to Resolve-Path.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>resolve-path \\Server01\public
This command resolves a Universal Naming Convention (UNC) path and returns the shares in the path.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>resolve-path c:\prog* -relative
..\Program Files
..\Program Files (x86)
..\programs.txt
This command returns relative paths for the directories at the root of the C: drive.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>resolve-path -literalPath test[xml]
This command resolves the path to the Test[xml] subdirectory of the current directory. It uses the LiteralPath parameter to indicate that the brackets are not regular expression characters.
###RELATED LINKS Online Version: Convert-Path Join-Path Split-Path Test-Path about_Providers ##Restart-Computer
###SYNOPSIS Restarts ("reboots") the operating system on local and remote computers.
###SYNTAX TODO
###DESCRIPTION The Restart-Computer cmdlet restarts the operating system on the local and remote computers. You can use the parameters of Restart-Computer to run the restart operations as a background job, to specify the authentication levels and alternate credentials, to limit the operations that run concurrently, and to force an immediate restart. Beginning in Windows PowerShell 3.0, you can wait for the restart to complete before running the next command, specify a waiting timeout and query interval, and wait for particular services to be available on the restarted computer. This feature makes it practical to use Restart-Computer in scripts and functions. You can also use the WSMan protocol to restart the computer, in case DCOM calls are blocked, such as by an enterprise firewall. This cmdlet requires Windows PowerShell remoting only when you use the AsJob parameter in a command.
###PARAMETERS
####AsJob [<SwitchParameter>]
Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. The job is created on the local computer and the results from remote computers are automatically returned to the local computer. To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet.
For more information about Windows PowerShell background jobs, see about_Jobs (http://go.microsoft.com/fwlink/?LinkID=113251) and about_Remote_Jobs (http://go.microsoft.com/fwlink/?LinkID=135184).
####ComputerName [<String[]>]
Specifies one or more remote computers. The default is the local computer. Type the NETBIOS name, an IP address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the Get-Credential cmdlet.
####Delay [<Int16>]
Determines how often Windows PowerShell queries the service that is specified by the For parameter to determine whether it is available after the computer is restarted. Specify a delay between queries, in seconds. The default value is 5 (seconds). This parameter is valid only with the Wait and For parameters. This parameter is introduced in Windows PowerShell 3.0.
####For [<WaitForServiceTypes>]
Waits until the specified service or feature is available after the computer is restarted. Specify one of the valid values. This parameter is valid only with the Wait parameter. Valid values are: -- Default: Waits for Windows PowerShell to restart. -- PowerShell: Can run commands in a Windows PowerShell remote session on the computer. -- WMI: Receives a reply to a Win32_ComputerSystem query for the computer. -- WinRM: Can establish a remote session to the computer by using WS-Management. This parameter is introduced in Windows PowerShell 3.0.
####Force [<SwitchParameter>]
Forces an immediate restart of the computers.
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use when calling WMI. (Restart-Computer uses WMI.) The default value is "Impersonate". Valid values are:
-- Default: Default impersonation.
-- Anonymous: Hides the identity of the caller. -- Identify: Allows objects to query the credentials of the caller. -- Impersonate: Allows objects to use the credentials of the caller.
####ThrottleLimit [<Int32>]
Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used. The throttle limit applies only to the current command, not to the session or to the computer.
####Timeout [<Int32>]
Specifies the duration of the wait, in seconds. When the timeout elapses, Restart-Computer returns the command prompt, even if the computers are not restarted. The default value, -1, represents an indefinite timeout. The Timeout parameter is valid only with the Wait parameter. This parameter is introduced in Windows PowerShell 3.0.
####Wait [<SwitchParameter>]
Suppresses the Windows PowerShell prompt and blocks the pipeline until all of the computers have restarted. You can use this parameter in a script to restart computers and then continue processing when the restart is complete. By default, the Wait parameter waits indefinitely for the computers to restart, but you can use the Timeout parameter to adjust the timing and the For and Delay parameters to wait for particular services to be available on the restarted computers. The Wait parameter is not valid when you are restarting the local computer. If the value of the ComputerName parameter contains the names of remote computers and the local computer, Restart-Computer generates a non-terminating error for the Wait parameter on the local computer, but it waits for the remote computers to restart. This parameter is introduced in Windows PowerShell 3.0.
####DcomAuthentication [<AuthenticationLevel>]
Specifies the authentication level that is used for the WMI connection. (Restart-Computer uses WMI.) The default value is Packet. Valid values are: -- Call: Call-level COM authentication
-- Connect: Connect-level COM authentication -- Default: Windows Authentication -- None: No COM authentication -- Packet: Packet-level COM authentication. -- PacketIntegrity: Packet Integrity-level COM authentication -- PacketPrivacy: Packet Privacy-level COM authentication. -- Unchanged: The authentication level is the same as the previous command. {For more information about the values of this parameter, see "AuthenticationLevel Enumerat... This parameter is introduced in Windows PowerShell 3.0.
####Protocol [<String>]
Specifies which protocol to use to restart the computers. Valid values are WSMan and DCOM. The default value is DCOM. This parameter is introduced in Windows PowerShell 3.0.
####WsmanAuthentication [<String>]
Specifies the mechanism that is used to authenticate the user's credentials when using the WSMan protocol. {Valid values are Basic, CredSSP, Default, Digest, Kerberos, and Negotiate. The default val... Caution: Credential Security Service Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. This parameter is introduced in Windows PowerShell 3.0.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.String You can pipe computer names to Restart-Computer. In Windows PowerShell 2.0, the ComputerName parameter takes input from the pipeline only by property name. In Windows PowerShell 3.0, the ComputerName parameter takes input from the pipeline by value.
###OUTPUTS ####None or System.Management.Automation.RemotingJob When you use the AsJob parameter, the cmdlet returns a job object. Otherwise, it does not generate any output.
###NOTES ####None or System.Management.Automation.RemotingJob This cmdlet uses the Win32Shutdown method of the WMI WIN32_OperatingSystem class. In Windows PowerShell 2.0, the AsJob parameter does not work reliably when you are restarting/stopping remote computers. In Windows PowerShell 3.0, the implementation is changed to resolve this problem.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Restart-Computer
This command restarts the local computer. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Restart-Computer -ComputerName Server01, Server02, localhost
This command restarts two remote computers, Server01 and Server02, and the local computer, identified as "localhost". -------------------------- EXAMPLE 3 --------------------------
The first command uses the AsJob parameter to run the command as a background job. The command saves the resulting job object in the $j variable.
PS C:\>$j = Restart-Computer -ComputerName Server01, Server02 -AsJob
The second command uses a pipeline operator to send the job object in $j to the Receive-Job cmdlet, which gets the job results. The command saves the results in the $Results variable.
PS C:\>$Results = $j | Receive-Job
The third command displays the result saved in the $Results variable.Because the AsJob parameter creates the job on the local computer and automatically returns the results to the local computer, you can run the Receive-Job command as a local command.
PS C:\>$Results
These commands run a Restart-Computer command as a background job on two remote computers, and then get the results. -------------------------- EXAMPLE 4 --------------------------
PS C:\>Restart-Computer -ComputerName Server01 -Impersonation Anonymous -Authentication PacketIntegrity
This command restarts the Server01 remote computer. The command uses customized impersonation and authentication settings. -------------------------- EXAMPLE 5 --------------------------
The first command uses the Get-Content cmdlet to get a list of computers in the domain from the Domain01.txt file. It saves the list in the $s variable.
PS C:\>$s = Get-Content Domain01.txt
The second command gets the credentials of a domain administrator and saves them in the $c variable.
PS C:\>$c = Get-Credential Domain01\Admin01
The third command restarts the computers. It uses the ComputerName parameter to submit the list of computers in the $s variable, the Force parameter to force an immediate restart, and the Credential parameter to submit the credentials saved in the $c variable. It also uses the ThrottleLimit parameter to limit the command to 10 concurrent connections.
PS C:\>Restart-Computer -ComputerName $s -Force -ThrottleLimit 10 -Credential $c
These commands force an immediate restart of all of the computers in Domain01. -------------------------- EXAMPLE 6 --------------------------
PS C:\>Restart-Computer -ComputerName Server01 -Wait -For PowerShell -Timeout 300 -Delay 2
This command restarts the Server01 remote computer and then waits up to 5 minutes (300 seconds) for Windows PowerShell to be available on the restarted computer before continuing. The command uses the Wait, For, and Timeout parameters to specify the conditions of the wait. It uses the Delay parameter to reduce the interval between queries to the remote computer that determine whether it is restarted. -------------------------- EXAMPLE 7 --------------------------
PS C:\>Restart-Computer -ComputerName Server01 -Protocol WSMan -WSManAuthentication Kerberos
This command restarts the Server01 remote computer by using the WSMan protocol, instead of DCOM, which is the default. It also uses Kerberos authentication to determine whether the current user has permission to restart the remote computer. These settings are designed for enterprises in which DCOM-based restarts fail because DCOM is blocked, such as by a firewall.
###RELATED LINKS Online Version: Add-Computer Checkpoint-Computer Rename-Computer Remove-Computer Restore-Computer Stop-Computer Test-Connection ##Restart-Service
###SYNOPSIS Stops and then starts one or more services.
###SYNTAX TODO
###DESCRIPTION The Restart-Service cmdlet sends a stop message and then a start message to the Windows Service Controller for a specified service. If a service was already stopped, it is started without notifying you of an error. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass an object that represents each service that you want to restart.
###PARAMETERS
####DisplayName <String[]>
Specifies the display names of services to be restarted. Wildcards are permitted.
####Exclude [<String[]>]
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####Force [<SwitchParameter>]
Restarts a service that has dependent services.
####Include [<String[]>]
Restarts only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####InputObject <ServiceController[]>
Specifies ServiceController objects that represent the services to be restarted. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Name <String[]>
Specifies the service names of the services to be restarted.
####PassThru [<SwitchParameter>]
Returns an object that represents the service. By default, this cmdlet does not generate any output.
###INPUTS ####System.ServiceProcess.ServiceController, System.String You can pipe a service object or a string that contains a service name to Restart-Service.
###OUTPUTS ####None or System.ServiceProcess.ServiceController When you use the PassThru parameter, Restart-Service generates a System.ServiceProcess.ServiceController object that represents the restarted service. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.ServiceProcess.ServiceController Restart-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions. To find the service names and display names of the services on your system, type "get-service". The service names appears in the Name column, and the display names appear in the DisplayName column.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Restart-Service winmgmt
This command restarts the Windows Management Instrumentation service (WinMgmt) on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Restart-Service -DisplayName net* -Exclude "net logon"
This command restarts the services that have a display name that begins with "Net", except for the "Net Logon" service.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Get-Service net* | Where-Object {$_.Status -eq "Stopped"} | Restart-Service
This command starts all of the stopped network services on the computer. It uses the Get-Service cmdlet to get objects representing the services whose service name begins with "net". (The optional Name parameter name is omitted.) The pipeline operator (|) sends the services object to the Where-Object cmdlet, which selects only the services with a status of "stopped." Another pipeline operator sends the selected services to Restart-Service. In practice, you would use the WhatIf parameter to see the effect of the command before using it.
###RELATED LINKS Online Version: Get-Service New-Service Resume-Service Set-Service Start-Service Stop-Service Suspend-Service ##Restore-Computer
###SYNOPSIS Starts a system restore on the local computer.
###SYNTAX TODO
###DESCRIPTION The Restore-Computer cmdlet restores the local computer to the specified system restore point. A Restore-Computer command restarts the computer. The restore is completed during the restart operation. System restore points and the Restore-Computer cmdlet are supported only on client operating systems, such as Windows 7, Windows Vista, and Windows XP.
###PARAMETERS
####RestorePoint <Int32>
Specifies the sequence number of the restore point. To find the sequence number, use Get-ComputerRestorePoint. This parameter is required.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None To run a Restore-Computer command on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. This cmdlet uses the Windows Management Instrumentation (WMI) SystemRestore class.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>restore-computer -RestorePoint 253
This command restores the local computer to the restore point with sequence number 253. Because the RestorePoint parameter is positional, you can omit the parameter name.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>restore-computer 255 -confirm
Confirm
Are you sure you want to perform this action?
Performing operation "Restore-Computer" .
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"):
This command restores the local computer to the restore point with sequence number 255. It uses the Confirm parameter to prompt the user before actually performing the operation.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Get-ComputerRestorePoint
PS C:\>Restore-Computer -RestorePoint 255
PS C:\>Get-ComputerRestorePoint -LastStatus
These commands run a system restore and then check its status. The first command uses the Get-ComputerRestorePoint cmdlet to get the restore points on the local computer. The second command uses Restore-Computer to restore the computer to the restore point with sequence number 255. The third command uses the LastStatus parameter of Get-ComputerRestorePoint cmdlet to check the status of the restore operation. Because the Restore-Computer command forces a restart, this command would be entered when the computer restarted.
###RELATED LINKS Online Version: Checkpoint-Computer Disable-ComputerRestore Enable-ComputerRestore Get-ComputerRestorePoint Restart-Computer ##Resume-Service
###SYNOPSIS Resumes one or more suspended (paused) services.
###SYNTAX TODO
###DESCRIPTION The Resume-Service cmdlet sends a resume message to the Windows Service Controller for each of the specified services. If they have been suspended, they will resume service. If they are currently running, the message is ignored. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass a service object that represents the services that you want to resume.
###PARAMETERS
####DisplayName <String[]>
Specifies the display names of the services to be resumed. Wildcards are permitted.
####Exclude [<String[]>]
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####Include [<String[]>]
Resumes only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be resumed. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Name <String[]>
Specifies the service names of the services to be resumed. The parameter name is optional. You can use "-Name" or its alias, "-ServiceName", or you can omit the parameter name.
####PassThru [<SwitchParameter>]
Returns an object representing the service. By default, this cmdlet does not generate any output.
###INPUTS ####System.ServiceProcess.ServiceController or System.String You can pipe a service object or a string that contains a service name to Resume-Service.
###OUTPUTS ####None or System.ServiceProcess.ServiceController When you use the PassThru parameter, Resume-Service generates a System.ServiceProcess.ServiceController object representing the resumed service. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.ServiceProcess.ServiceController The status of services that have been suspended is "Paused". When services are resumed, their status is "Running". Resume-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions. To find the service names and display names of the services on your system, type "get-service". The service names appear in the Name column, and the display names appear in the DisplayName column.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>resume-service sens
This command resumes the System Event Notification service (the service name is represented in the command by "sens") on the local computer. The command uses the Name parameter to specify the service name of the service, but the command omits the parameter name because the parameter name is optional.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-service | where-object {$_.Status -eq "Paused"} | resume-service
This command resumes all of the suspended (paused) services on the computer. The first command gets all of the services on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects the services with a Status property of "Paused". The next pipeline operator sends the results to Resume-Service, which resumes the paused services. In practice, you would use the WhatIf parameter to determine the effect of the command before running it without WhatIf.
###RELATED LINKS Online Version: Get-Service New-Service Restart-Service Set-Service Start-Service Stop-Service Suspend-Service ##Set-Content
###SYNOPSIS Writes or replaces the content in an item with new content.
###SYNTAX TODO
###DESCRIPTION The Set-Content cmdlet is a string-processing cmdlet that writes or replaces the content in the specified item, such as a file. Whereas the Add-Content cmdlet appends content to a file, Set-Content replaces the existing content. You can type the content in the command or send content through the pipeline to Set-Content.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Changes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies the path to the item that will receive the content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Returns an object representing the content. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the item that will receive the content. Wildcards are permitted.
####Value <Object[]>
Specifies the new content for the item.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.Object You can pipe an object that contains the new value for the item to Set-Content.
###OUTPUTS ####None or System.String When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.String You can also refer to Set-Content by its built-in alias, "sc". For more information, see about_Aliases. Set-Content is designed for string processing. If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File. The Set-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>set-content -path C:\Test1\test*.txt -value "Hello, World"
This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World". This example shows how to specify content by typing it in the command.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-date | set-content C:\Test1\date.csv
This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content. If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>(get-content Notice.txt) | foreach-object {$_ -replace "Warning", "Caution"} | set-content Notice.txt
This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. It uses the Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. Without them, the command will fail because the two functions will be trying to access the same file.
###RELATED LINKS Online Version: Add-Content Clear-Content Get-Content about_Providers ##Set-Item
###SYNOPSIS Changes the value of an item to the value specified in the command.
###SYNTAX TODO
###DESCRIPTION The Set-Item cmdlet changes the value of an item, such as a variable or registry key, to the value specified in the command.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to set items that cannot otherwise be changed, such as read-only alias or variables. The cmdlet cannot change constant aliases or variables. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions.
####Include [<String[]>]
Changes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####LiteralPath <String[]>
Specifies a path to the location of the new items. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Passes an object representing the item to the pipeline. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies a path to the location of the new items. Wildcards are permitted.
####Value [<Object>]
Specifies a new value for the item.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.Object You can pipe an object that represents the new value of the item to Set-Item.
###OUTPUTS ####None or an object representing the new or changed item. When you use the Passthru parameter, Set-Item generates an object representing the item. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or an object representing the new or changed item. You can also refer to Set-Item by its built-in alias, "si". For more information, see about_Aliases. The Set-Item cmdlet is not supported by the Windows PowerShell FileSystem provider. To change the values of items in the file system, use Set-Content. In the Registry drives, HKLM: and HKCU:, Set-Item changes the data in the (Default) value of a registry key. To create and change the names of registry keys, use New-Item and Rename-Item. To change the names and data in registry values, use New-ItemProperty, Set-ItemProperty, and Rename-ItemProperty. The Set-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>set-item -path alias:np -value c:\windows\notepad.exe
This command creates an alias of "np" for Notepad.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>set-item -path env:UserRole -value Administrator
This command uses the Set-Item cmdlet to change the value of the "UserRole" environment variable to "Administrator".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>set-item -path function:prompt -value {'PS '+ $(Get-Date -format t) + " " + $(Get-Location) + '> '}
This command uses the Set-Item cmdlet to change the "prompt" function so that it displays the time before the path.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>set-item -path function:prompt -options "AllScope,ReadOnly"
This command sets the AllScope and ReadOnly options for the "prompt" function. This command uses the Options dynamic parameter of the Set-Item cmdlet. The Options parameter is available in Set-Item only when you use it with the Alias or Function provider.
###RELATED LINKS Online Version: Clear-Item Copy-Item Get-Item Invoke-Item Move-Item New-Item Remove-Item Rename-Item about_Providers ##Set-ItemProperty
###SYNOPSIS Creates or changes the value of a property of an item.
###SYNTAX TODO
###DESCRIPTION The Set-ItemProperty cmdlet changes the value of the property of the specified item. You can use the cmdlet to establish or change the properties of items. For example, you can use Set-ItemProperty to set the value of the IsReadOnly property of a file object to true. You also use Set-ItemProperty to create and change registry values and data. For example, you can add a new registry entry to a key and establish or change its value.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Specifies those items upon which the cmdlet is not to act, and includes all others.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Force [<SwitchParameter>]
Allows the cmdlet to set a property on items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_Providers.
####Include [<String[]>]
Specifies only those items upon which the cmdlet will act, excluding all others.
####InputObject <PSObject>
Specifies the object that has the properties that you want to change. Enter a variable that contains the object or a command that gets the object.
####LiteralPath <String[]>
Specifies a path to the item property. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Name <String>
Specifies the name of the property.
####PassThru [<SwitchParameter>]
Returns an object representing the item property. By default, this cmdlet does not generate any output.
####Path <String[]>
Specifies the path to the items with the property to be set.
####Value <Object>
Specifies the value of the property.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.Management.Automation.PSObject You can pipe objects to Set-ItemProperty.
###OUTPUTS ####None or System.Management.Automation.PSCustomObject When you use the PassThru parameter, Set-ItemProperty generates a PSCustomObject object that represents the item that was changed and its new property value. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Management.Automation.PSCustomObject The Set-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>set-itemproperty -path c:\GroupFiles\final.doc -name IsReadOnly -value $true
This command sets the value of the IsReadOnly property of the final.doc file to true. The command uses the Set-ItemProperty cmdlet to change the value of the property of the final.doc file. It uses the Path parameter to specify the file. It uses the Name parameter to specify the name of the property and the Value parameter to specify the new value. The $true automatic variable represents a value of TRUE. For more information, see about_Automatic_Variables. The file is a System.IO.FileInfo object and IsReadOnly is just one of its properties. To see all of the properties and methods of a FileInfo object, pipe the file to the Get-Member cmdlet. For example, "final.doc | get-member".
-------------------------- EXAMPLE 2 --------------------------
PS C:\>set-itemproperty -path HKLM:\Software\MyCompany -name NoOfEmployees -value 823
PS C:\>get-itemproperty -path HKLM:\Software\MyCompany
PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
PSChildName : mycompany
PSDrive : HKLM
PSProvider : Microsoft.PowerShell.Core\Registry
NoOfLocations : 2
NoOfEmployees : 823
PS C:\>set-itemproperty -path HKLM:\Software\MyCompany -name NoOfEmployees -value 824
PS C:\>get-itemproperty -path HKLM:\Software\MyCompany
PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
PSChildName : mycompany
PSDrive : HKLM
PSProvider : Microsoft.PowerShell.Core\Registry
NoOfLocations : 2
NoOfEmployees : 824
This example shows how to use Set-ItemProperty to create a new registry entry and to assign a value to the entry. It creates the NoOfEmployees entry in the MyCompany key in HKLM\Software key and sets its value to 823. Because registry entries are considered to be properties of the registry keys (which are items), you use Set-ItemProperty to create registry entries, and to establish and change their values. The first command uses the Set-ItemProperty cmdlet to create the registry entry. It uses the Path parameter to specify the path to the HKLM: drive and the Software\MyCompany key. It uses the Name parameter to specify the entry name and the Value parameter to specify a value. The second command uses the Get-ItemProperty cmdlet to see the new registry entry. If you use the Get-Item or Get-ChildItem cmdlets, the entries do not appear because they are properties of a key, not items or child items. The third command changes the value of the NoOfEmployees entry to 824. You can also use the New-ItemProperty cmdlet to create the registry entry and its value and then use Set-ItemProperty to change the value. For more information about the HKLM: drive, type "get-help get-psdrive". For more information about using Windows PowerShell to manage the registry, type "get-help registry".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-childitem weekly.txt | set-itemproperty -name IsReadOnly -value $true
These commands show how to use a pipeline operator (|) to send an item to Set-ItemProperty. The first part of the command uses the Get-ChildItem cmdlet to get an object that represents the Weekly.txt file. The command uses a pipeline operator to send the file object to Set-ItemProperty. The Set-ItemProperty command uses the Name and Value parameters to specify the property and its new value. This command is equivalent to using the InputObject parameter to specify the object that Get-ChildItem gets.
###RELATED LINKS Online Version: Clear-ItemProperty Copy-ItemProperty Get-ItemProperty Move-ItemProperty New-ItemProperty Remove-ItemProperty Rename-ItemProperty about_Providers ##Set-Location
###SYNOPSIS Sets the current working location to a specified location.
###SYNTAX TODO
###DESCRIPTION The Set-Location cmdlet sets the working location to a specified location. That location could be a directory, a sub-directory, a registry location, or any provider path. You can also use the StackName parameter of the Set-Location cmdlet to make a named location stack the current location stack. For more information about location stacks, see the Notes.
###PARAMETERS
####LiteralPath <String>
Specifies a path to the location. The value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####PassThru [<SwitchParameter>]
Returns a System.Management.Automation.PathInfo object that represents the location. By default, this cmdlet does not generate any output.
####Path [<String>]
This parameter is used to specify the path to a new working location.
####StackName [<String>]
Makes the specified location stack the current location stack. Enter a location stack name. To indicate the unnamed default location stack, type "$null" or an empty string (""). The Location cmdlets act on the current stack unless you use the StackName parameter to specify a different stack.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter can only be used when a transaction is in progress. For more information, see about_Transactions.
###INPUTS ####System.String You can pipe a string that contains a path (but not a literal path) to Set-Location.
###OUTPUTS ####None, System.Management.Automation.PathInfo, System.Management.Automation.PathInfoStack When you use the PassThru parameter, Set-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.
###NOTES ####None, System.Management.Automation.PathInfo, System.Management.Automation.PathInfoStack The Set-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers. A "stack" is a last-in, first-out list in which only the most recently added item is accessible. You add items to a stack in the order that you use them, and then retrieve them for use in the reverse order. Windows PowerShell lets you store provider locations in location stacks. Windows PowerShell creates an unnamed default location stack and you can create multiple named location stacks. If you do not specify a stack name, Windows PowerShell uses the current location stack. By default, the unnamed default location is the current location stack, but you can use the Set-Location cmdlet to change the current location stack. To manage location stacks, use the Windows PowerShell Location cmdlets, as follows. -- To add a location to a location stack, use the Push-Location cmdlet. -- To get a location from a location stack, use the Pop-Location cmdlet. -- To display the locations in the current location stack, use the Stack parameter of the Get-Location cmdlet. To display the locations in a named location stack, use the StackName parameter of the Get-Location cmdlet. -- To create a new location stack, use the StackName parameter of the Push-Location cmdlet. If you specify a stack that does not exist, Push-Location creates the stack. -- To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. The unnamed default location stack is fully accessible only when it is the current location stack. If you make a named location stack the current location stack, you cannot no longer use Push-Location or Pop-Location cmdlets add or get items from the default stack or use Get-Location command to display the locations in the unnamed stack. To make the unnamed stack the current stack, use the StackName parameter of the Set-Location cmdlet with a value of $null or an empty string ("").
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>set-location HKLM:
PS HKLM:\>
This command set the current location to the root of the HKLM: drive.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>set-location env: -passthru
Path
----
Env:\
PS Env:\>
This command sets the current location to the root of the Env: drive. It uses the Passthru parameter to direct Windows PowerShell to return a PathInfo (System.Management.Automation.PathInfo) object that represents the Env: location.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>set-location C:
This command sets the current location C: drive in the file system provider.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>set-location -stackName WSManPaths
This command makes the WSManPaths location stack the current location stack. The location cmdlets use the current location stack unless a different location stack is specified in the command. For information about location stacks, see the Notes.
###RELATED LINKS Online Version: Get-Location Pop-Location Push-Location about_Providers ##Set-Service
###SYNOPSIS Starts, stops, and suspends a service, and changes its properties.
###SYNTAX TODO
###DESCRIPTION The Set-Service cmdlet changes the properties of a local or remote service, including the status, description, display name, and start mode. You can use this cmdlet to start, stop, or suspend (pause) a service. To identify the service, enter its service name or submit a service object, or pipe a service name or service object to Set-Service.
###PARAMETERS
####ComputerName [<String[]>]
Specifies one or more computers. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of a remote computer. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Set-Service even if your computer is not configured to run remote commands.
####Description [<String>]
Specifies a new description for the service. The service description appears in Services in Computer Management. Description is not a property of the ServiceController object that Get-Service gets. To see the service description, use Get-WmiObject to get a Win32_Service object that represents the service.
####DisplayName [<String>]
Specifies a new display name for the service.
####InputObject [<ServiceController>]
Specifies a ServiceController object that represents the service to be changed. Enter a variable that contains the object, or type a command or expression that gets the object, such as a Get-Service command. You can also pipe a service object to Set-Service.
####Name <String>
Specifies the service name of the service to be changed. Wildcards are not permitted. You can also pipe a service name to Set-Service.
####PassThru [<SwitchParameter>]
Returns objects that represent the services that were changed. By default, this cmdlet does not generate any output.
####StartupType [<ServiceStartMode>]
Changes the start mode of the service. Valid values for StartupType are: -- Automatic: Start when the system starts. -- Manual: Starts only when started by a user or program. -- Disabled: Cannot be started.
####Status [<String>]
Starts, stops, or suspends (pauses) the services. Valid values are: -- Running: Starts the service. -- Stopped: Stops the service. -- Paused: Suspends the service.
###INPUTS ####System.ServiceProcess.ServiceController, System.String You can pipe a service object or a string that contains a service name to Set-Service.
###OUTPUTS ####System.ServiceProcess.ServiceController This cmdlet does not return any objects.
###NOTES ####System.ServiceProcess.ServiceController To use Set-Service on Windows Vista and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. Set-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions. To find the service names and display names of the services on your system, type "get-service". The service names appear in the Name column and the display names appear in the DisplayName column.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>set-service -name lanmanworkstation -DisplayName "LanMan Workstation"
This command changes the display name of the lanmanworkstation service to "LanMan Workstation". (The default is "Workstation".)
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-wmiobject win32_service -filter "name = 'SysmonLog'"
ExitCode : 0
Name : SysmonLog
ProcessId : 0
StartMode : Manual
State : Stopped
Status : OK
PS C:\>set-service sysmonlog -startuptype automatic
PS C:\>get-wmiobject win32_service -filter "name = 'SysmonLog'"
ExitCode : 0
Name : SysmonLog
ProcessId : 0
StartMode : Auto
State : Stopped
Status : OK
PS C:\>get-wmiobject win32_service | format-table Name, StartMode -auto
Name StartMode
---- ---------
AdtAgent Auto
Alerter Disabled
ALG Manual
AppMgmt Manual
...
These commands get the startup type of the Performance Logs and Alerts (SysmonLog) service, set the start mode to automatic, and then display the result of the change. These commands use the Get-WmiObject cmdlet to get the Win32_Service object for the service, because the ServiceController object that Get-Service returns does not include the start mode. The first command uses the Get-WmiObject cmdlet to get the Windows Management Instrumentation (WMI) object that represents the SysmonLog service. The default output of this command displays the start mode of the service. The second command uses Set-Service to change the start mode to automatic. Then, the first command is repeated to display the change. The final command displays the start mode of all services on the computer.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>set-service -name Schedule -computername S1 -description "Configures and schedules tasks."
PS C:\>get-wmiobject win32_service -computername s1 | where-object {$_.Name -eq "Schedule"} | format-list Name, Description
These commands change the description of the Task Scheduler service on the S1 remote computer and then display the result. These commands use the Get-WmiObject cmdlet to get the Win32_Service object for the service, because the ServiceController object that Get-Service returns does not include the service description. The first command uses a Set-Service command to change the description. It identifies the service by using the service name of the service, "Schedule". The second command uses the Get-WmiObject cmdlet to get an instance of the WMI Win32_Service that represents the Task Scheduler service. The first element in the command gets all instances of the Win32_service class. The pipeline operator (|) passes the result to the Where-Object cmdlet, which selects instances with a value of "Schedule" in the Name property. Another pipeline operator sends the result to the Format-List cmdlet, which formats the output as a list with only the Name and Description properties.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>set-service winrm -status Running -passthru -computername Server02
This command starts the WinRM service on the Server02 computer. The command uses the Status parameter to specify the desired status ("running") and the PassThru parameter to direct Set-Service to return an object that represents the WinRM service.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>get-service schedule -computername S1, S2 | set-service -status paused
This command suspends the Schedule service on the S1 and S2 remote computers. It uses the Get-Service cmdlet to get the service. A pipeline operator (|) sends the service to the Set-Service cmdlet, which changes its status to "Paused".
-------------------------- EXAMPLE 6 --------------------------
PS C:\>$s = get-service schedule
PS C:\>set-service -inputobject $s -status stopped
These commands stop the Schedule service on the local computer. The first command uses the Get-Service cmdlet to get the Schedule service. The command saves the service in the $s variable. The second command uses the Set-Service cmdlet to change the status of the Schedule service to "Stopped". It uses the InputObject parameter to submit the service stored in the $s variable, and it uses the Status parameter to specify the desired status.
###RELATED LINKS Online Version: Get-Service New-Service Restart-Service Resume-Service Start-Service Stop-Service Suspend-Service ##Set-WmiInstance
###SYNOPSIS Creates or updates an instance of an existing Windows Management Instrumentation (WMI) class.
###SYNTAX TODO
###DESCRIPTION The Set-WmiInstance cmdlet creates or updates an instance of an existing WMI class. The created or updated instance is written to the WMI repository. New CIM cmdlets, introduced Windows PowerShell 3.0, perform the same tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) standards and with the Common Information Model (CIM) standard, which enables the cmdlets to use the same techniques to manage Windows computers and those running other operating systems. Instead of using Set-WmiInstance, consider using the Set-CimInstance or New-CimInstance cmdlets.
###PARAMETERS
####Arguments [<Hashtable>]
Specifies the name of the property to be changed and the new value for that property. The name and value must be in a name-value pair. The name-value pair is passed on the command-line as a hash table. For example: -argument @{Setting1=1; Setting2=5; Setting3="test"}.
####AsJob [<SwitchParameter>]
Runs the command as a background job. Use this parameter to run commands that take a long time to finish. When you use the AsJob parameter, the command returns an object that represents the background job and then displays the command prompt. You can continue to work in the session while the job finishes. If Set-WmiObject is used against a remote computer, the job is created on the local computer, and the results from remote computers are automatically returned to the local computer. To manage the job, use the cmdlets that contain the Job noun (the Job cmdlets). To get the job results, use the Receive-Job cmdlet. Note: To use this parameter with remote computers, the local and remote computers must be configured for remoting. Additionally, you must start Windows PowerShell by using the "Run as administrator" option in Windows Vista and later versions of Windows,. For more information, see about_Remote_Requirements. For more information about Windows PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
####Authentication [<AuthenticationLevel>]
Specifies the authentication level to be used with the WMI connection. Valid values are: -1: Unchanged 0: Default 1: None (No authentication in performed.) 2: Connect (Authentication is performed only when the client establishes a relationship with the application.) 3: Call (Authentication is performed only at the beginning of each call when the application receives the request.) 4: Packet (Authentication is performed on all the data that is received from the client.) 5: PacketIntegrity (All the data that is transferred between the client and the application is authenticated and verified.) 6: PacketPrivacy (The properties of the other authentication levels are used, and all the data is encrypted.)
####Authority [<String>]
Specifies the authority to use to authenticate the WMI connection. You can specify standard NTLM or Kerberos authentication. To use NTLM, set the authority setting to ntlmdomain:, where identifies a valid NTLM domain name. To use Kerberos, specify kerberos:<ServerName>". You cannot include the authority setting when you connect to the local computer.
####Class <String>
Specifies the name of a WMI class.
####ComputerName [<String[]>]
Runs the command on the specified computers. The default is the local computer. Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more computers. To specify the local computer, type the computer name, a dot (.), or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01", "Domain01\User01", or [email protected]. Or, enter a PSCredential object, such as an object that is returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.
####EnableAllPrivileges [<SwitchParameter>]
Enables all the privileges of the current user before the command makes the WMI call .
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use. Valid values are: 0: Default (Reads the local registry for the default impersonation level, which is usually set to "3: Impersonate".) 1: Anonymous (Hides the credentials of the caller.) 2: Identify (Allows objects to query the credentials of the caller.) 3: Impersonate (Allows objects to use the credentials of the caller.) 4: Delegate (Allows objects to permit other objects to use the credentials of the caller.)
####InputObject <ManagementObject>
Specifies a ManagementObject object to use as input. When this parameter is used, all other parameters ,except the Arguments parameter, are ignored.
####Locale [<String>]
Specifies the preferred locale for WMI objects. The Locale parameter is specified in an array in the MS_ format in the preferred order.
####Namespace [<String>]
When used with the Class parameter, this parameter specifies the WMI repository namespace where the referenced WMI class is located.
####Path <String>
Specifies a WMI object path to the instance that you want to create or update.
####PutType [<PutType>]
Indicates whether the WMI instance should be created or updated. Valid values are: UpdateOnly: Updates an existing WMI instance. CreateOnly: Creates a new WMI instance. UpdateOrCreate: Updates the WMI instance if it exists or creates a new instance if an instance does not exist.
####ThrottleLimit [<Int32>]
Allows the user to specify a throttling value for the number of WMI operations that can be executed simultaneously. This parameter is used together with the AsJob parameter. The throttle limit applies only to the current command, not to the session or to the computer.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None This cmdlet does not accept input.
###OUTPUTS ####None This cmdlet does not generate output.
###NOTES ####None
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Set-WMIInstance -class Win32_WMISetting -argument @{LoggingLevel=2}
__GENUS : 2
__CLASS : Win32_WMISetting
__SUPERCLASS : CIM_Setting
__DYNASTY : CIM_Setting
__RELPATH : Win32_WMISetting=@
__PROPERTY_COUNT : 27
__DERIVATION : {CIM_Setting}
__SERVER : SYSTEM01
__NAMESPACE : root\cimv2
__PATH : \\SYSTEM01\root\cimv2:Win32_WMISetting=@
ASPScriptDefaultNamespace : \\root\cimv2
ASPScriptEnabled : False
AutorecoverMofs : {%windir%\system32\wbem\cimwin32.mof, %windir%\system32\wbem\ncprov.mof, %windir%\syst
em32\wbem\wmipcima.mof, %windir%\system32\wbem\secrcw32.mof...}
AutoStartWin9X :
BackupInterval :
BackupLastTime :
BuildVersion : 6001.18000
Caption :
DatabaseDirectory : C:\Windows\system32\wbem\repository
DatabaseMaxSize :
Description :
EnableAnonWin9xConnections :
EnableEvents : False
EnableStartupHeapPreallocation : False
HighThresholdOnClientObjects :
HighThresholdOnEvents : 20000000
InstallationDirectory : C:\Windows\system32\wbem
LastStartupHeapPreallocation :
LoggingDirectory : C:\Windows\system32\wbem\Logs\
LoggingLevel : 2
LowThresholdOnClientObjects :
LowThresholdOnEvents : 10000000
MaxLogFileSize : 65536
MaxWaitOnClientObjects :
MaxWaitOnEvents : 2000
MofSelfInstallDirectory :
SettingID :
This command sets the WMI logging level to 2. The command passes the property to be set and the value (together considered a value pair) in the argument parameter. The parameter takes a hash table that is defined by the @{property = value} construction. The class information that is returned reflects the new value.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>set-wmiinstance -class win32_environment -argument @{Name="testvar";VariableValue="testvalue";UserName="<SYSTEM>"}
__GENUS : 2
__CLASS : Win32_Environment
__SUPERCLASS : CIM_SystemResource
__DYNASTY : CIM_ManagedSystemElement
__RELPATH : Win32_Environment.Name="testvar",UserName="<SYSTEM>"
__PROPERTY_COUNT : 8
__DERIVATION : {CIM_SystemResource, CIM_LogicalElement, CIM_ManagedSystemElement}
__SERVER : SYSTEM01
__NAMESPACE : root\cimv2
__PATH : \\SYSTEM01\root\cimv2:Win32_Environment.Name="testvar",UserName="<SYSTEM>"
Caption : <SYSTEM>\testvar
Description : <SYSTEM>\testvar
InstallDate :
Name : testvar
Status : OK
SystemVariable : True
UserName : <SYSTEM>
VariableValue : testvalue
This command creates the testvar environment variable that has the value "testvalue". It does this by creating a new instance of the Win32_Environment WMI class. Note that this operation requires appropriate credentials and that you may need to restart Windows PowerShell to see the new environment variable.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Set-WMIInstance -class Win32_WMISetting -argument @{LoggingLevel=2} -computername system01, system02, system03
__GENUS : 2
__CLASS : Win32_WMISetting
__SUPERCLASS : CIM_Setting
__DYNASTY : CIM_Setting
__RELPATH : Win32_WMISetting=@
__PROPERTY_COUNT : 27
__DERIVATION : {CIM_Setting}
__SERVER : SYSTEM01
__NAMESPACE : root\cimv2
__PATH : \\SYSTEM01\root\cimv2:Win32_WMISetting=@
ASPScriptDefaultNamespace : \\root\cimv2
ASPScriptEnabled : False
AutorecoverMofs : {%windir%\system32\wbem\cimwin32.mof, %windir%\system32\wbem\ncprov.mof, %windir%\syst
em32\wbem\wmipcima.mof, %windir%\system32\wbem\secrcw32.mof...}
AutoStartWin9X :
BackupInterval :
BackupLastTime :
BuildVersion : 6001.18000
Caption :
DatabaseDirectory : C:\Windows\system32\wbem\repository
DatabaseMaxSize :
Description :
EnableAnonWin9xConnections :
EnableEvents : False
EnableStartupHeapPreallocation : False
HighThresholdOnClientObjects :
HighThresholdOnEvents : 20000000
InstallationDirectory : C:\Windows\system32\wbem
LastStartupHeapPreallocation :
LoggingDirectory : C:\Windows\system32\wbem\Logs\
LoggingLevel : 2
LowThresholdOnClientObjects :
LowThresholdOnEvents : 10000000
MaxLogFileSize : 65536
MaxWaitOnClientObjects :
MaxWaitOnEvents : 2000
MofSelfInstallDirectory :
SettingID :
...
This command sets the WMI logging level to 2. The command passes the property to be set and the value (together considered a value pair) in the argument parameter. The parameter takes a hash table that is defined by the @{property = value} construction. The returned class information reflects the new value.
###RELATED LINKS Online Version: Get-WSManInstance Invoke-WSManAction New-WSManInstance Remove-WSManInstance Get-WmiObject Invoke-WmiMethod Remove-WmiObject ##Show-ControlPanelItem
###SYNOPSIS Opens control panel items.
###SYNTAX TODO
###DESCRIPTION The Show-ControlPanelItem cmdlet opens control panel items on the local computer. You can use it to open control panel items by name, category, or description, even on systems that do not have a user interface, and you can pipe control panel items from Get-ControlPanelItem to Show-ControlPanelItem. Show-ControlPanelItem searches only the control panel items that can be opened on the system. On computers that do not have Control Panel or File Explorer, Show-ControlPanelItem searches only control panel items that can open without these components. This cmdlet is introduced in Windows PowerShell 3.0. It works only on Windows 8 and Windows Server 2012. Because this cmdlet requires a user interface, it does not work on Server Core installations of Windows Server.
###PARAMETERS
####CanonicalName <String[]>
Opens control panel items with the specified canonical names or name patterns. Wildcards are permitted. If you enter multiple names, Get-ControlPanelItem opens the control panel items that match any of the names, as though the items in the name list were separated by an "or" operator.
####InputObject [<ControlPanelItem[]>]
Specifies the control panel items to open by submitting control panel item objects. Enter a variable that contains the control panel item objects, or type a command or expression that gets the control panel item objects, such as a Get-ControlPanelItem command.
####Name <String[]>
Opens control panel items with the specified names or name patterns. Wildcards are permitted. If you enter multiple names, Get-ControlPanelItem opens the control panel items that match any of the names, as though the items in the name list were separated by an "or" operator.
###INPUTS ####System.String, Microsoft.PowerShell.Commands.ControlPanelItem You can pipe a name or control panel item object to Show-ControlPanelItem.
###OUTPUTS ####None This cmdlet does not return any output.
###NOTES ####None
###EXAMPLES Example 1: Open a Control Panel Item
PS C:\>Show-ControlPanelItem –Name AutoPlay
Example 2: Pipe a control panel item to Show-ControlPanelItem
PS C:\>Get-ControlPanelItem –Name "Windows Firewall" | Show-ControlPanelItem
This command opens the Windows Firewall control panel item on the local computer. It uses the Get-ControlPanelItem cmdlet to get the control panel item and the Show-ControlPanelItem cmdlet to open it. Example 3: Use a file name to open a control panel item
PS C:\>appwiz
This command opens the Programs and Features control panel item by using its application name. The .cpl file name extension is not required in the command. This method is an alternative to using a Show-ControlPanelItem command. In Windows PowerShell 3.0, you can omit the .cpl file name extension for control panel item files because it is included in the value of the PathExt environment variable.
###RELATED LINKS Online Version: Get-ControlPanelItem ##Show-EventLog
###SYNOPSIS Displays the event logs of the local or a remote computer in Event Viewer.
###SYNTAX TODO
###DESCRIPTION The Show-EventLog cmdlet opens Event Viewer on the local computer and displays in it all of the classic event logs on the local computer or a remote computer. To open Event Viewer on Windows Vista and later versions of Windows, the current user must be a member of the Administrators group on the local computer. The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.
###PARAMETERS
####ComputerName [<String>]
Specifies a remote computer. Show-EventLog displays the event logs from the specified computer in Event Viewer on the local computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-EventLog even if your computer is not configured to run remote commands.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None The Windows PowerShell command prompt returns as soon as Event Viewer opens. You can work in the current session while Event Viewer is open. Because this cmdlet requires a user interface, it does not work on Server Core installations of Windows Server.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>show-eventlog
This command opens Event Viewer and displays in it the classic event logs on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>show-eventlog -computername Server01
This command opens Event Viewer and displays in it the classic event logs on the Server01 computer.
###RELATED LINKS Online Version: Clear-EventLog Get-EventLog Limit-EventLog New-EventLog Remove-EventLog Write-EventLog ##Split-Path
###SYNOPSIS Returns the specified part of a path.
###SYNTAX TODO
###DESCRIPTION The Split-Path cmdlet returns only the specified part of a path, such as the parent directory, a child directory, or a file name. It can also get items that are referenced by the split path and tell whether the path is relative or absolute. You can use this cmdlet to get or submit only a selected part of a path.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####IsAbsolute [<SwitchParameter>]
Returns TRUE ($True) if the path is absolute and FALSE ($False) if it is relative. An absolute path has a length greater than zero and does not use a dot ( . ) to indicate the current path.
####Leaf [<SwitchParameter>]
Returns only the last item or container in the path. For example, in the path "C:\Test\Logs\Pass1.log", it returns only "Pass1.log".
####LiteralPath <String[]>
Specifies the paths to be split. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####NoQualifier [<SwitchParameter>]
Returns the path without the qualifier. For the FileSystem or registry providers, the qualifier is the drive of the provider path, such as C: or HKCU:. For example, in the path "C:\Test\Logs\Pass1.log", it returns only "\Test\Logs\Pass1.log".
####Parent [<SwitchParameter>]
Returns only the parent containers of the item or of the container specified by the path. For example, in the path "C:\Test\Logs\Pass1.log", it returns "C:\Test\Logs". The Parent parameter is the default split location parameter.
####Path <String[]>
Specifies the paths to be split. Wildcards are permitted. If the path includes spaces, enclose it in quotation marks. You can also pipe a path to Split-Path.
####Qualifier [<SwitchParameter>]
Returns only the qualifier of the specified path. For the FileSystem or registry providers, the qualifier is the drive of the provider path, such as C: or HKCU:.
####Resolve [<SwitchParameter>]
Displays the items that are referenced by the resulting split path instead of displaying the path elements.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path to Split-Path.
###OUTPUTS ####System.String, System.Boolean The Split-Path cmdlet returns text strings. When you use the Resolve parameter, Split-Path returns a string that describes the location of the items; it does not return objects that represent the items, such as a FileInfo or RegistryKey object. When you use the IsAbsolute parameter, Split-Path returns a Boolean value.
###NOTES ####System.String, System.Boolean The split location parameters (Qualifier, Parent, Leaf, and NoQualifier) are exclusive. You can use only one in each command. The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators. You can use the Path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers. The Split-Path cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>split-path "HKCU:\Software\Microsoft" -qualifier
HKCU:
This command returns only the qualifier (the drive) of the path.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>split-path "C:\Test\Logs\*.log" -leaf -resolve
Pass1.log
Pass2.log
...
This command displays the files that are referenced by the split path. Because this path is split to the last item (the "leaf"), only the file names of the paths are displayed. The Resolve parameter tells Split-Path to display the items that the split path references, instead of displaying the split path. Like all Split-Path commands, this command returns strings. It does not return FileInfo Objects representing the files.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>split-path "C:\WINDOWS\system32\WindowsPowerShell\V1.0\about_*.txt"
C:\WINDOWS\system32\WindowsPowerShell\V1.0
This command returns only the parent containers of the path. Because it does not include any parameters to specify the split, Split-Path uses the split location default, which is Parent.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>split-path ".\My Pictures\*.jpg" -IsAbsolute
False
This command determines whether the path is relative or absolute. In this case, because the path is relative to the current directory, which is represented by a dot (.), it returns FALSE ($false).
-------------------------- EXAMPLE 5 --------------------------
PS C:\>set-location (split-path $profile)
PS C:\Documents and Settings\User01\My Documents\WindowsPowerShell>
This command changes your location to the directory that contains the Windows PowerShell profile. The command in parentheses uses the Split-Path cmdlet to return only the parent of the path stored in the built-in $Profile variable. (The Parent parameter is the default split location parameter, so you can omit it from the command.) The parentheses direct Windows PowerShell to run the command first. This is a handy way to navigate to a directory with a long path name.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>'C:\Documents and Settings\User01\My Documents\My Pictures' | split-path
C:\Documents and Settings\User01\My Documents
This command uses a pipeline operator (|) to send a path to the Split-Path cmdlet. The path is enclosed in quotation marks to indicate that it is a single token.
###RELATED LINKS Online Version: Convert-Path Join-Path Resolve-Path Test-Path about_Providers ##Start-Process
###SYNOPSIS Starts one or more processes on the local computer.
###SYNTAX TODO
###DESCRIPTION Starts one or more processes on the local computer. To specify the program that runs in the process, enter an executable file or script file, or a file that can be opened by using a program on the computer. If you specify a non-executable file, Start-Process starts the program that is associated with the file, much like the Invoke-Item cmdlet. You can use the parameters of Start-Process to specify options, such as loading a user profile, starting the process in a new window, or using alternate credentials.
###PARAMETERS
####ArgumentList [<String[]>]
Specifies parameters or parameter values to use when starting the process. The parameter name ("ArgumentList") is optional.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. Type a user-name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the Get-Credential cmdlet. By default, the cmdlet uses the credentials of the current user.
####FilePath <String>
Specifies the path (optional) and file name of the program that runs in the process. Enter the name of an executable file or of a document, such as a .txt or .doc file, that is associated with a program on the computer. This parameter is required. If you specify only a file name, use the WorkingDirectory parameter to specify the path.
####LoadUserProfile [<SwitchParameter>]
Loads the Windows user profile stored in the HKEY_USERS registry key for the current user. The default value is FALSE. This parameter does not affect the Windows PowerShell profiles. (See about_Profiles.)
####NoNewWindow [<SwitchParameter>]
Start the new process in the current console window. By default Windows PowerShell opens a new window. You cannot use the NoNewWindow and WindowStyle parameters in the same command.
####PassThru [<SwitchParameter>]
Returns a process object for each process that the cmdlet started. By default, this cmdlet does not generate any output.
####RedirectStandardError [<String>]
Sends any errors generated by the process to a file that you specify. Enter the path and file name. By default, the errors are displayed in the console.
####RedirectStandardInput [<String>]
Reads input from the specified file. Enter the path and file name of the input file. By default, the process gets its input from the keyboard.
####RedirectStandardOutput [<String>]
Sends the output generated by the process to a file that you specify. Enter the path and file name. By default, the output is displayed in the console.
####UseNewEnvironment [<SwitchParameter>]
Use new environment variables specified for the process. By default, the started process runs with the environment variables specified for the computer and user.
####Verb [<String>]
Specifies a verb to use when starting the process. The verbs that are available are determined by the file name extension of the file that runs in the process. The following table shows the verbs for some common process file types. File type Verbs
.cmd------Edit, Open, Print, Runas .exe------Open, RunAs .txt------Open, Print, PrintTo .wav------Open, Play To find the verbs that can be used with the file that runs in a process, use the New-Object cmdlet to create a System.Diagnostics.ProcessStartInfo object for the file. The available verbs are in the Verbs property of the ProcessStartInfo object. For details, see the examples.
####Wait [<SwitchParameter>]
Waits for the specified process to complete before accepting more input. This parameter suppresses the command prompt or retains the window until the process completes.
####WindowStyle [<ProcessWindowStyle>]
Specifies the state of the window that is used for the new process. Valid values are Normal, Hidden, Minimized, and Maximized. The default value is Normal. You cannot use the WindowStyle and NoNewWindow parameters in the same command.
####WorkingDirectory [<String>]
Specifies the location of the executable file or document that runs in the process. The default is the current directory.
###INPUTS ####None You cannot pipe input to Start-Process.
###OUTPUTS ####None or System.Diagnostics.Process When you use the PassThru parameter, Start-Process generates a System.Diagnostics.Process. Otherwise, this cmdlet does not return any output.
###NOTES ####None or System.Diagnostics.Process This cmdlet is implemented by using the Start method of the System.Diagnostics.Process class. For more information about this method, see "Process.Start Method" in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=143602.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>start-process sort.exe
This command starts a process that uses the Sort.exe file in the current directory. The command uses all of the default values, including the default window style, working directory, and credentials.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>start-process myfile.txt -workingdirectory "C:\PS-Test" -verb Print
This command starts a process that prints the C:\PS-Test\MyFile.txt file.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>start-process Sort.exe -RedirectStandardInput Testsort.txt -RedirectStandardOutput Sorted.txt -RedirectStandardError SortError.txt -UseNewEnvironment
This command starts a process that sorts items in the Testsort.txt file and returns the sorted items in the Sorted.txt files. Any errors are written to the SortError.txt file. The UseNewEnvironment parameter specifies that the process runs with its own environment variables.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>start-process notepad -wait -windowstyle Maximized
This command starts the Notepad process. It maximizes the window and retains the window until the process completes.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>start-process powershell -verb runAs
This command starts Windows PowerShell with the "Run as administrator" option.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>$startExe = new-object System.Diagnostics.ProcessStartInfo -args PowerShell.exe
PS C:\>$startExe.verbs
open
runas
# Starts a PowerShell process in a new console window.
PS C:\>start-process powershell.exe -verb open
# Starts a PowerShell process with "Run as Administrator" permissions.
PS C:\>start-process powershell.exe -verb runas
These commands show how to find the verbs that can be used when starting a process, and the effect of using the verbs to start the process. The available verbs are determined by the file name extension of the file that runs in the process. To find the verbs for a process, create a System.Diagnostics.ProcessStartInfo object for the process file and look in the Verbs property of the object. In this example, we'll use the PowerShell.exe file that runs in the PowerShell process. The first command uses the New-Object cmdlet to create a System.Diagnostics.ProcessStartInfo object for PowerShell.exe, the file that runs in the PowerShell process. The command saves the ProcessStartInfo object in the $startExe variable. The second command displays the values in the Verbs property of the ProcessStartInfo object in the $startExe variable. The results show that you can use the Open and Runas verbs with PowerShell.exe, or with any process that runs a .exe file. The third command starts a PowerShell process with the Open verb. The Open verb starts the process in a new console window. The fourth command starts a PowerShell process with the RunAs verb. The RunAs verb starts the process with permissions of a member of the Administrators group on the computer. This is the same as starting Windows PowerShell with the "Run as administrator" option.
###RELATED LINKS Online Version: Debug-Process Get-Process Start-Service Stop-Process Wait-Process ##Start-Service
###SYNOPSIS Starts one or more stopped services.
###SYNTAX TODO
###DESCRIPTION The Start-Service cmdlet sends a start message to the Windows Service Controller for each of the specified services. If a service is already running, the message is ignored without error. You can specify the services by their service names or display names, or you can use the InputObject parameter to supply a service object representing the services that you want to start.
###PARAMETERS
####DisplayName <String[]>
Specifies the display names of the services to be started. Wildcards are permitted.
####Exclude [<String[]>]
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####Include [<String[]>]
Starts only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be started. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Name <String[]>
Specifies the service names for the service to be started. The parameter name is optional. You can use "-Name" or its alias, "-ServiceName", or you can omit the parameter name.
####PassThru [<SwitchParameter>]
Returns an object representing the service. By default, this cmdlet does not generate any output.
###INPUTS ####System.ServiceProcess.ServiceController, System.String You can pipe objects that represent the services or strings that contain the service names to Start-Service.
###OUTPUTS ####None or System.ServiceProcess.ServiceController When you use the PassThru parameter, Start-Service generates a System.ServiceProcess.ServiceController object representing the service. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.ServiceProcess.ServiceController You can also refer to Start-Service by its built-in alias, "sasv". For more information, see about_Aliases. Start-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions. To find the service names and display names of the services on your system, type "get-service". The service names appear in the Name column, and the display names appear in the DisplayName column. You can start only the services that have a start type of "Manual" or "Automatic". You cannot start the services with a start type of "Disabled". If a Start-Service command fails with the message "Cannot start service on computer," use a Get-WmiObject command to find the start type of the service and, if necessary, use a Set-Service command to change the start type of the service. Some services, such as Performance Logs and Alerts (SysmonLog) stop automatically if they have no work to do. When Windows PowerShell starts a service that stops itself almost immediately, it displays the following message: "Service start failed."
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>start-service -name eventlog
This command starts the EventLog service on the local computer. It uses the Name parameter to identify the service by its service name.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>start-service -displayname *remote* -whatif
This command tells what would happen if you started the services with a display name that includes "remote". It uses the DisplayName parameter to specify the services by their display name instead of by their service name. And, it uses the WhatIf parameter to tell what would happen if the command were executed instead of executing the command.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$s = get-service wmi
PS C:\>start-service -InputObject $s -passthru | format-list >> services.txt
These commands start the Windows Management Instrumentation (WMI) service on the computer and add a record of the action to the services.txt file. The first command uses the Get-Service cmdlet to get an object representing the WMI service and store it in the $s variable. The second command uses the Start-Service cmdlet to start the WMI service. It identifies the service by using the InputObject parameter to pass the $s variable containing the WMI service object to Start-Service. Then, it uses the PassThru parameter to create an object that represents the starting of the service. Without this parameter, Start-Service does not create any output. The pipeline operator (|) passes the object that Start-Service creates to the Format-List cmdlet, which formats the object as a list of its properties. The append redirection operator (>>) redirects the output to the services.txt file, where it is added to the end of the existing file.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>start-service tlntsvr
Start-Service : Service 'Telnet (TlntSvr)' cannot be started due to the following error: Cannot start service TlntSvr on computer '.'.
At line:1 char:14
+ start-service <<<< tlntsvr
PS C:\>get-wmiobject win32_service | where-object {$_.Name -eq "tlntsvr"}
ExitCode : 0
Name : TlntSvr
ProcessId : 0
StartMode : Disabled
State : Stopped
Status : OK
PS C:\>set-service tlntsvr -startuptype manual
PS C:\>start-service tlntsvr
This series of commands shows how to start a service when the start type of the service is "Disabled". The first command, which uses the Start-Service cmdlet to start the Telnet service (tlntsvr), fails. The second command uses the Get-WmiObject cmdlet to get the Tlntsvr service. This command retrieves an object with the start type property in the StartMode field. The resulting display reveals that the start type of the Tlntsvr service is "Disabled". The next command uses the Set-Service cmdlet to change the start type of the Tlntsvr service to "Manual". Now, we can resubmit the Start-Service command. This time, the command succeeds. To verify that the command succeeded, run Get-Service.
###RELATED LINKS Online Version: Get-Service New-Service Restart-Service Resume-Service Set-Service Stop-Service Suspend-Service ##Start-Transaction
###SYNOPSIS Starts a transaction.
###SYNTAX TODO
###DESCRIPTION The Start-Transaction cmdlet starts a transaction, which is a series of commands that are managed as a unit. A transaction can be completed ("committed"), or it can be completely undone ("rolled back") so that any data changed by the transaction is restored to its original state. Because the commands in a transaction are managed as a unit, either all commands are committed or all commands are rolled back. By default, transactions are rolled back automatically if any command in the transaction generates an error, but you can use the RollbackPreference parameter to change this behavior. The cmdlets used in a transaction must be designed to support transactions. Cmdlets that support transactions have a UseTransaction parameter. To perform transactions in a provider, the provider must support transactions. The Windows PowerShell Registry provider in Windows Vista and later versions of Windows supports transactions. You can also use the Microsoft.PowerShell.Commands.Management.TransactedString class to include expressions in transactions on any version of Windows that supports Windows PowerShell. Other Windows PowerShell providers can also support transactions. Only one transaction can be active at a time. If you start a new, independent transaction while a transaction is in progress (neither completed nor undone), the new transaction becomes the active transaction, and you must commit or roll back the new transaction before making any changes to the original transaction. The Start-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_Transactions.
###PARAMETERS
####Independent [<SwitchParameter>]
Starts a transaction that is independent of any transactions in progress. By default, if you use Start-Transaction while another transaction is in progress, a new subscriber is added to the transaction in progress. This parameter has an effect only when a transaction is already in progress in the session. By default, if you use Start-Transaction while a transaction is in progress, the existing transaction object is reused and the subscriber count is incremented. The effect is much like joining the original transaction. An Undo-Transaction command rolls back the entire the transaction. To complete the transaction, you must enter a Complete-Transaction command for each subscriber. Because most transactions that are in progress at the same time are related, the default is sufficient for most uses. If you use the Independent parameter, a new transaction is created that can be completed or undone without affecting the original transaction. However, because only one transaction can be active at a time, you must complete or roll back the new transaction before resuming work on the original transaction.
####RollbackPreference [<RollbackSeverity>]
Specifies the conditions under which a transaction is automatically rolled back. The default value is "Error". Valid values are: -- Error: The transaction is rolled back automatically if a terminating or non-terminating error occurs. "Error" is the default. -- Terminating error: The transaction is rolled back automatically if a terminating error occurs. -- Never: The transaction is never rolled back automatically.
####Timeout [<Int32>]
Specifies the maximum time, in minutes, that the transaction is active. When the time-out expires, the transaction is automatically rolled back. By default, there is no time-out for transactions that are started at the command line. When transactions are started by a script, the default time-out is 30 minutes.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> undo-transaction
These commands start and then roll back a transaction. Because the transaction is rolled back, no changes are made to the registry.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> complete-transaction
These commands start and then complete a transaction. No changes are made to the registry until the Complete-Transaction command is used.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
# Start-Transaction (-rollbackpreference error)
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -Name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -path NoPath -Name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
At line:1 char:9
+ new-item <<<< -path . -name MyCompany -UseTransaction
# Start-Transaction (-rollbackpreference never)
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany {}
PS HKCU:\Software> complete-transaction
# Succeeds
This example demonstrates the effect of changing the RollbackPreference parameter value. In the first set of commands, the Start-Transaction command does not use the RollbackPreference parameter. As a result, the default value ("Error") is used. When an error occurs in a transaction command (the specified path does not exist), the transaction is automatically rolled back. In the second set of commands, the Start-Transaction command uses the RollbackPreference parameter with a value of "Never". As a result, when an error occurs in a transaction command, the transaction is still active and can be completed successfully. Because most transactions must be performed without error, the default value of the RollbackPreference parameter is typically preferred.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> start-transaction
PS HKCU:\software> get-transaction
PS HKCU:\software> new-item MyCompany2 -UseTransaction
PS HKCU:\software> complete-transaction
PS HKCU:\software> complete-transaction
PS HKCU:\Software> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 Active
This example shows the effect of using the Start-Transaction command while a transaction is in progress. The effect is much like joining the transaction in progress. Although this is a simplified command, this scenario commonly occurs when the transaction involves running a script that includes a complete transaction. The first Start-Transaction command starts the transaction. The first New-Item command is part of the transaction. The second Start-Transaction command adds a new subscriber to the transaction. The Get-Transaction command now returns a transaction with a subscriber count of 2. The second New-Item command is part of the same transaction. No changes are made to the registry until the entire transaction is completed. To complete the transaction, you must enter two Complete-Transaction commands, one for each subscriber. If you were to roll back the transaction at any point, the entire transaction would be rolled back for both subscribers.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> start-transaction -independent
PS HKCU:\software> get-transaction
PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
PS HKCU:\Software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
MyKey
-----
123
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 1 MyCompany {MyKey}
This example shows the effect of using the Independent parameter of Start-Transaction to start a transaction while another transaction is in progress. In this case, the new transaction is rolled back without affecting the original transaction. Although the transactions are logically independent, because only one transaction can be active at a time, you must roll back or commit the newest transaction before resuming work on the original transaction. The first set of commands starts a transaction. The New-Item command is part of the first transaction. In the second set of commands, the Start-Transaction command uses the Independent parameter. The Get-Transaction command that follows shows the transaction object for the active transaction (the newest one). The subscriber count is equal to 1, showing that the transactions are unrelated. When the active transaction is rolled back by using an Undo-Transaction command, the original transaction becomes active again. The New-ItemProperty command, which is part of the original transaction, completes without error, and the original transaction can be completed by using the Complete-Transaction command. As a result, the registry is changed.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany1 -UseTransaction
PS HKCU:\software> new-item MyCompany2
PS HKCU:\software> new-item MyCompany3 -UseTransaction
PS HKCU:\software> dir my*
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
PS HKCU:\Software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany2 {}
PS HKCU:\Software> complete-transaction
PS HKCU:\Software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany1 {}
0 0 MyCompany2 {}
0 0 MyCompany3 {}
This example demonstrates that commands that are submitted while a transaction is in progress can be included in the transaction or not included. Only commands that use the UseTransaction parameter are part of the transaction. The first and third New-Item commands use the UseTransaction parameter. These commands are part of the transaction. Because the second New-Item command does not use the UseTransaction parameter, it is not part of the transaction. The first "dir" command shows the effect. The second New-Item command is completed immediately, but the first and third New-Item commands are not effective until the transaction is committed. The Complete-Transaction command commits the transaction. As a result, the second "dir" command shows that all of the new items are added to the registry.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>start-transaction -timeout 2
# Wait two minutes...
PS C:\>get-transaction
PS C:\>new-item HKCU:\Software\MyCompany -UseTransaction
PS C:\>start-transaction -timeout 2
# Wait two minutes...
PS C:\>> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- -----------
Error 1 RolledBack
PS C:\>new-item HKCU:\Software\MyCompany -UseTransaction
New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
At line:1 char:9
+ new-item <<<< MyCompany -UseTransaction
This command uses the Timeout parameter of Start-Transaction to start a transaction that must be completed within two minutes. If the transaction is not complete when the timeout expires, it is rolled back automatically. When the timeout expires, you are not notified, but the Status property of the transaction object is set to RolledBack and commands that use the UseTransaction parameter fail.
###RELATED LINKS Online Version: Complete-Transaction Get-Transaction Undo-Transaction Use-Transaction about_Transactions ##Stop-Computer
###SYNOPSIS Stops (shuts down) local and remote computers.
###SYNTAX TODO
###DESCRIPTION The Stop-Computer cmdlet shuts down computers remotely. It can also shut down the local computer. You can use the parameters of Stop-Computer to run the shutdown operations as a background job, to specify the authentication levels and alternate credentials, to limit the concurrent connections that are created to run the command, and to force an immediate shut down. This cmdlet does not require Windows PowerShell remoting unless you use the AsJob parameter.
###PARAMETERS
####AsJob [<SwitchParameter>]
Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. For more information, see about_Remote_Requirements". When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. The job is created on the local computer and the results from remote computers are automatically returned to the local computer. To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. For more information about Windows PowerShell background jobs, see about_Jobs and see about_Remote_Jobs.
####Authentication [<AuthenticationLevel>]
Specifies the authentication level that is used for the WMI connection. (Stop-Computer uses WMI.) The default value is Packet. Valid values are: Unchanged: The authentication level is the same as the previous command. Default: Windows Authentication. None: No COM authentication. Connect: Connect-level COM authentication. Call: Call-level COM authentication. Packet: Packet-level COM authentication. PacketIntegrity: Packet Integrity-level COM authentication. PacketPrivacy: Packet Privacy-level COM authentication.
####ComputerName [<String[]>]
Stops the specified computers. The default is the local computer. Type the NETBIOS name, IP address, or fully qualified domain name of one or more computers in a comma-separated list. To specify the local computer, type the computername or "localhost". This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the Get-Credential cmdlet.
####Force [<SwitchParameter>]
Forces an immediate shut down of the computers.
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use when calling WMI. (Stop-Computer uses WMI.) The default value is "Impersonate". Valid values are: Default: Default impersonation. Anonymous: Hides the identity of the caller. Identify: Allows objects to query the credentials of the caller. Impersonate: Allows objects to use the credentials of the caller.
####ThrottleLimit [<Int32>]
Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used. The throttle limit applies only to the current command, not to the session or to the computer.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None or System.Management.Automation.RemotingJob When you use the AsJob parameter, the cmdlet returns a job object (System.Management.Automation.RemotingJob). Otherwise, it does not generate any output.
###NOTES ####None or System.Management.Automation.RemotingJob This cmdlet uses the Win32Shutdown method of the Win32_OperatingSystem WMI class. In Windows PowerShell 2.0, the AsJob parameter does not work reliably when you are restarting/stopping remote computers. In Windows PowerShell 3.0, the implementation is changed to resolve this problem.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>stop-computer
This command shuts down the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>stop-computer -computername Server01, Server02, localhost
This command stops two remote computers, Server01 and Server02, and the local computer, identified as "localhost".
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$j = stop-computer -computername Server01, Server02 -asjob
PS C:\>$results = $j | receive-job
PS C:\>$results
These commands run a Stop-Computer command as a background job on two remote computers, and then get the results. The first command uses the AsJob parameter to run the command as a background job. The command saves the resulting job object in the $j variable. The second command uses a pipeline operator to send the job object in $j to the Receive-Job cmdlet, which gets the job results. The command saves the results in the $results variable. The third command displays the result saved in the $results variable. Because the AsJob parameter creates the job on the local computer and automatically returns the results to the local computer, you can run the Receive-Job command as a local command.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>stop-computer -comp Server01 -impersonation anonymous -authentication PacketIntegrity
This command restarts the Server01 remote computer. The command uses customized impersonation and authentication settings.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>$s = get-content domain01.txt
PS C:\>$c = get-credential domain01\admin01
PS C:\>stop-computer -computername $s -force -throttlelimit 10 -credential $c
These commands force an immediate shut down of all of the computers in Domain01. The first command gets a list of computers in the domain and saves it in the $s variable. The second command gets the credentials of a domain administrator and saves them in the $c variable. The third command shuts down the computers. It uses ComputerName parameter to submit the list of computers in the $s variable, the Force parameter to force an immediate shutdown, and the Credential parameter to submit the credentials saved in the $c variable. It also uses the ThrottleLimit parameter to limit the command to 10 concurrent connections.
###RELATED LINKS Online Version: Add-Computer Checkpoint-Computer Remove-Computer Rename-Computer Restart-Computer Restore-Computer Test-Connection ##Stop-Process
###SYNOPSIS Stops one or more running processes.
###SYNTAX TODO
###DESCRIPTION The Stop-Process cmdlet stops one or more running processes. You can specify a process by process name or process ID (PID), or pass a process object to Stop-Process. Stop-Process works only on processes running on the local computer. On Windows Vista and later versions of Windows, to stop a process that is not owned by the current user, you must start Windows PowerShell with the "Run as administrator" option. Also, you are prompted for confirmation unless you use the Force parameter.
###PARAMETERS
####Force [<SwitchParameter>]
Stops the specified processes without prompting for confirmation. By default, Stop-Process prompts for confirmation before stopping any process that is not owned by the current user. To find the owner of a process, use the Get-WmiMethod cmdlet to get a Win32_Process object that represents the process, and then use the GetOwner method of the object.
####Id <Int32[]>
Specifies the process IDs of the processes to be stopped. To specify multiple IDs, use commas to separate the IDs. To find the PID of a process, type "get-process". The parameter name ("Id") is optional.
####InputObject <Process[]>
Stops the processes represented by the specified process objects. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Name <String[]>
Specifies the process names of the processes to be stopped. You can type multiple process names (separated by commas) or use wildcard characters.
####PassThru [<SwitchParameter>]
Returns an object representing the process. By default, this cmdlet does not generate any output.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.Diagnostics.Process You can pipe a process object to Stop-Process.
###OUTPUTS ####None or System.Diagnostics.Process When you use the PassThru parameter, Stop-Process returns a System.Diagnostics.Process object that represents the stopped process. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.Diagnostics.Process You can also refer to Stop-Process by its built-in aliases, "kill" and "spps". For more information, see about_Aliases. You can also use the properties and methods of the Windows Management Instrumentation (WMI) Win32_Process object in Windows PowerShell. For more information, see Get-WmiObject and the WMI SDK. When stopping processes, be aware that stopping a process can stop process and services that depend on the process. In an extreme case, stopping a process can stop Windows.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>stop-process -name notepad
This command stops all instances of the Notepad process on the computer. (Each instance of Notepad runs in its own process.) It uses the Name parameter to specify the processes, all of which have the same name. If you were to use the ID parameter to stop the same processes, you would have to list the process IDs of each instance of Notepad.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>stop-process -id 3952 -confirm -passthru
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Process" on Target "notepad (3952)".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help
(default is "Y"):y
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
41 2 996 3212 31 3952 notepad
This command stops a particular instance of the Notepad process. It uses the process ID, 3952, to identify the process. The Confirm parameter directs Windows PowerShell to prompt the user before stopping the process. Because the prompt includes the process name, as well as its ID, this is best practice. The PassThru parameter passes the process object to the formatter for display. Without this parameter, there would be no display after a Stop-Process command.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>calc
PS C:\>$p = get-process calc
PS C:\>stop-process -inputobject $p
PS C:\>get-process | where-object {$_.HasExited}
This series of commands starts and stops the Calc process and then detects processes that have stopped. The first command ("calc") starts an instance of the calculator. The second command ("$p = get-process calc"), uses the Get-Process cmdlet to get an object representing the Calc process and store it in the $p variable. The third command ("stop-process -inputobject $p") uses the Stop-Process cmdlet to stop the Calc process. It uses the InputObject parameter to pass the object to Stop-Process. The last command gets all of the processes on the computer that were running but that are now stopped. It uses the Get-Process cmdlet to get all of the processes on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects the ones where the value of the HasExited property is TRUE. HasExited is just one property of process objects. To find all the properties, type "get-process | get-member".
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-process lsass | stop-process
Stop-Process : Cannot stop process 'lsass (596)' because of the following error: Access is denied
At line:1 char:34
+ get-process lsass | stop-process <<<<
[ADMIN]: PS C:\>get-process lsass | stop-process
Warning!
Are you sure you want to perform this action?
Performing operation 'Stop-Process' on Target 'lsass(596)'
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"):
[ADMIN]: PS C:\>get-process lsass | stop-process -force
[ADMIN]: PS C:\>
These commands show the effect of using the Force parameter to stop a process that is not owned by the user. The first command uses the Get-Process cmdlet to get the Lsass process. A pipeline operator sends the process to the Stop-Process cmdlet to stop it. As shown in the sample output, the first command fails with an "Access denied" message, because this process can be stopped only by a member of the Administrator's group on the computer. When Windows PowerShell is opened with the "Run as administrator" option, and the command is repeated, Windows PowerShell prompts you for confirmation. The second command uses the Force parameter to suppress the prompt. As a result, the process is stopped without confirmation.
###RELATED LINKS Online Version: Debug-Process Get-Process Start-Process Stop-Process Wait-Process ##Stop-Service
###SYNOPSIS Stops one or more running services.
###SYNTAX TODO
###DESCRIPTION The Stop-Service cmdlet sends a stop message to the Windows Service Controller for each of the specified services. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass a service object representing the services that you want to stop.
###PARAMETERS
####DisplayName <String[]>
Specifies the display names of the services to be stopped. Wildcards are permitted.
####Exclude [<String[]>]
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####Force [<SwitchParameter>]
Allows the cmdlet to stop a service even if that service has dependent services.
####Include [<String[]>]
Stops only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be stopped. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Name <String[]>
Specifies the service names of the services to be stopped. Wildcards are permitted. The parameter name is optional. You can use "Name" or its alias, "ServiceName", or you can omit the parameter name.
####PassThru [<SwitchParameter>]
Returns an object representing the service. By default, this cmdlet does not generate any output.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.ServiceProcess.ServiceController or System.String You can pipe a service object or a string that contains the name of a service to Stop-Service.
###OUTPUTS ####None or System.ServiceProcess.ServiceController When you use the PassThru parameter, Stop-Service generates a System.ServiceProcess.ServiceController object representing the service. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.ServiceProcess.ServiceController You can also refer to Stop-Service by its built-in alias, "spsv". For more information, see about_Aliases. Stop-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions. To find the service names and display names of the services on your system, type "get-service". The service names appear in the Name column and the display names appear in the DisplayName column.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>stop-service sysmonlog
This command stops the Performance Logs and Alerts (SysmonLog) service on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>get-service -displayname telnet | stop-service
This command stops the Telnet service on the local computer. The command uses the Get-Service cmdlet to get an object representing the Telnet service. The pipeline operator (|) pipes the object to the Stop-Service cmdlet, which stops the service.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-service iisadmin | format-list -property name, dependentservices
PS C:\>stop-service iisadmin -force -confirm
The Stop-Service command stops the IISAdmin service on the local computer. Because stopping this service also stops the services that depend on the IISAdmin service, it is best to precede the Stop-Service command with a command that lists the services that depend on the IISAdmin service. The first command lists the services that depend on IISAdmin. It uses the Get-Service cmdlet to get an object representing the IISAdmin service. The pipeline operator (|) passes the result to the Format-List cmdlet. The command uses the Property parameter of Format-List to list only the Name and DependentServices properties of the service. The second command stops the IISAdmin service. The Force parameter is required to stop a service that has dependent services. The command uses the Confirm parameter to request confirmation from the user before stopping each service.
###RELATED LINKS Online Version: Get-Service New-Service Restart-Service Resume-Service Set-Service Start-Service Suspend-Service ##Suspend-Service
###SYNOPSIS Suspends (pauses) one or more running services.
###SYNTAX TODO
###DESCRIPTION The Suspend-Service cmdlet sends a suspend message to the Windows Service Controller for each of the specified services. While suspended, the service is still running, but its action is halted until resumed, such as by using Resume-Service. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass a service object representing the services that you want to suspend.
###PARAMETERS
####DisplayName <String[]>
Specifies the display names of the services to be suspended. Wildcards are permitted.
####Exclude [<String[]>]
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####Include [<String[]>]
Suspends only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.
####InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be suspended. Enter a variable that contains the objects, or type a command or expression that gets the objects.
####Name <String[]>
Specifies the service names of the services to be suspended. Wildcards are permitted. The parameter name is optional. You can use "Name" or its alias, "ServiceName", or you can omit the parameter name.
####PassThru [<SwitchParameter>]
Returns an object representing the service. By default, this cmdlet does not generate any output.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####System.ServiceProcess.ServiceController or System.String You can pipe a service object or a string that contains a service name to Suspend-Service.
###OUTPUTS ####None or System.ServiceProcess.ServiceController When you use the PassThru parameter, Suspend-Service generates a System.ServiceProcess.ServiceController object representing the service. Otherwise, this cmdlet does not generate any output.
###NOTES ####None or System.ServiceProcess.ServiceController Suspend-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions. Also, Suspend-Service can suspend only services that support being suspended and resumed. To determine whether a particular service can be suspended, use the Get-Service cmdlet with the CanPauseAndContinue property. For example, "get-service wmi | format-list name, canpauseandcontinue". To find all services on the computer that can be suspended, type "get-service | where-object {$_.canpauseandcontinue -eq "True"}". To find the service names and display names of the services on your system, type "get-service". The service names appear in the Name column, and the display names appear in the DisplayName column.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>suspend-service -displayname "Telnet"
This command suspends the Telnet service (Tlntsvr) service on the local computer.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>suspend-service -name lanman* -whatif
This command tells what would happen if you suspended the services that have a service name that begins with "lanman". To suspend the services, rerun the command without the WhatIf parameter.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>get-service schedule | suspend-service
This command uses the Get-Service cmdlet to get an object that represents the Task Scheduler (Schedule) service on the computer. The pipeline operator (|) passes the result to the Suspend-Service cmdlet, which suspends the service.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>get-service | where-object {$_.canpauseandcontinue -eq "True"} | suspend-service -confirm
This command suspends all of the services on the computer that can be suspended. It uses the Get-Service cmdlet to get objects representing the services on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects only the services that have a value of "True" for the CanPauseAndContinue property. Another pipeline operator passes the results to the Suspend-Service cmdlet. The Confirm parameter prompts you for confirmation before suspending each of the services.
###RELATED LINKS Online Version: Get-Service New-Service Restart-Service Resume-Service Set-Service Start-Service Stop-Service ##Test-ComputerSecureChannel
###SYNOPSIS Tests and repairs the secure channel between the local computer and its domain.
###SYNTAX TODO
###DESCRIPTION The Test-ComputerSecureChannel cmdlet verifies that the secure channel between the local computer and its domain is working correctly by checking the status of its trust relationships. If a connection fails, you can use the Repair parameter to try to restore it. Test-ComputerSecureChannel returns "True" if the secure channel is working correctly and "False" if it is not. This result lets you use the cmdlet in conditional statements in functions and scripts. To get more detailed test results, use the Verbose parameter. This cmdlet works much like NetDom.exe. Both NetDom and Test-ComputerSecureChannel use the NetLogon service to perform the actions.
###PARAMETERS
####Repair [<SwitchParameter>]
Removes and then rebuilds the secure channel established by the NetLogon service. Use this parameter to try to restore a connection that has failed the test (returned "False".) To use this parameter, the current user must be a member of the Administrators group on the local computer.
####Server [<String>]
Uses the specified domain controller to run the command. If this parameter is omitted, Test-ComputerSecureChannel selects a default domain controller for the operation.
####Credential [<PSCredential>]
Runs the command with the permissions of the specified user. Type a user-name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one that the Get-Credential cmdlet returns. By default, the cmdlet uses the credentials of the current user. The Credential parameter is designed for use in commands that use the Repair parameter to repair the secure channel between the computer and the domain.
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Boolean The cmdlet returns "True" when the connection is working correctly and "False" when it is not.
###NOTES ####System.Boolean To run a Test-ComputerSecureChannel command on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option. Test-ComputerSecureChannel is implemented by using the I_NetLogonControl2 function, which controls various aspects of the Netlogon service.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>test-computersecurechannel
True
This command tests the secure channel between the local computer and the domain to which it is joined.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>test-computersecurechannel -server DCName.fabrikam.com
True
This command specifies a preferred domain controller for the test.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>Test-ComputerSecureChannel -repair
True
This command resets the secure channel between the local computer and its domain.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>test-computerSecureChannel -verbose
VERBOSE: Performing operation "Test-ComputerSecureChannel" on Target "SERVER01".
True
VERBOSE: "The secure channel between 'SERVER01' and 'net.fabrikam.com' is alive and working correctly."
This command uses the Verbose common parameter to request detailed messages about the operation. For more information about the Verbose parameter, see about_CommonParameters.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>set-alias tcsc test-computersecurechannel
if (!(tcsc))
{write-host "Connection failed. Reconnect and retry."}
else { &(.\get-servers.ps1) }
This example shows how to use Test-ComputerSecureChannel to test a connection before running a script that requires the connection. The first command uses the Set-Alias cmdlet to create an alias for the cmdlet name. This saves space and prevents typing errors. The If statement checks the value that Test-ComputerSecureChannel returns before running a script.
###RELATED LINKS Online Version: Checkpoint-Computer Reset-ComputerMachinePassword Restart-Computer Stop-Computer ##Test-Connection
###SYNOPSIS Sends ICMP echo request packets ("pings") to one or more computers.
###SYNTAX TODO
###DESCRIPTION The Test-Connection cmdlet sends Internet Control Message Protocol (ICMP) echo request packets ("pings") to one or more remote computers and returns the echo response replies. You can use this cmdlet to determine whether a particular computer can be contacted across an Internet Protocol (IP) network. You can use the parameters of Test-Connection to specify both the sending and receiving computers, to run the command as a background job, to set a timeout and number of pings, and to configure the connection and authentication. Unlike the traditional "ping" command, Test-Connection returns a Win32_PingStatus object that you can investigate in Windows PowerShell, but you can use the Quiet parameter to force it to return only a Boolean value.
###PARAMETERS
####AsJob [<SwitchParameter>]
Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. For more information, see about_Remote_Requirements. When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. The job is created on the local computer and the results from remote computers are automatically returned to the local computer. To get the job results, use the Receive-Job cmdlet. For more information about Windows PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
####Authentication [<AuthenticationLevel>]
Specifies the authentication level that is used for the WMI connection. (Test-Connection uses WMI.) Valid values are: Unchanged: The authentication level is the same as the previous command. Default: Windows Authentication. None: No COM authentication. Connect: Connect-level COM authentication. Call: Call-level COM authentication. Packet: Packet-level COM authentication. PacketIntegrity: Packet Integrity-level COM authentication. PacketPrivacy: Packet Privacy-level COM authentication.
####BufferSize [<Int32>]
Specifies the size, in bytes, of the buffer sent with this command. The default value is 32.
####ComputerName <String[]>
Specifies the computers to ping. Type the computer names or type IP addresses in IPv4 or IPv6 format. Wildcard characters are not permitted. This parameter is required. This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
####Count [<Int32>]
Specifies the number of echo requests to send. The default value is 4.
####Credential [<PSCredential>]
Specifies a user account that has permission to send a ping request from the source computer. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the Get-Credential cmdlet. The Credential parameter is valid only when the Source parameter is used in the command. The credentials do not affect the destination computer.
####Delay [<Int32>]
Specifies the interval between pings, in seconds.
####Impersonation [<ImpersonationLevel>]
Specifies the impersonation level to use when calling WMI. (Test-Connection uses WMI.) The default value is "Impersonate". Valid values are: Default: Default impersonation. Anonymous: Hides the identity of the caller. Identify: Allows objects to query the credentials of the caller. Impersonate: Allows objects to use the credentials of the caller.
####Quiet [<SwitchParameter>]
Suppresses all errors and returns $True if any pings succeeded and $False if all failed.
####Source <String[]>
Specifies the names of the computers where the ping originates. Enter a comma-separated list of computer names. The default is the local computer.
####ThrottleLimit [<Int32>]
Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used. The throttle limit applies only to the current command, not to the session or to the computer.
####TimeToLive [<Int32>]
Specifies the maximum time, in seconds, that each echo request packet ("pings") is active. Enter an integer between 1 and 255. The default value is 80 (seconds). The alias of the TimeToLive parameter is TTL.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Management.ManagementObject#root\cimv2\Win32_PingStatus, System.Management.Automation.RemotingJob, System.Boolean When you use the AsJob parameter, the cmdlet returns a job object. When you use the Quiet parameter, it returns a Boolean. Otherwise, this cmdlet returns a Win32_PingStatus object for each ping.
###NOTES ####System.Management.ManagementObject#root\cimv2\Win32_PingStatus, System.Management.Automation.RemotingJob, System.Boolean This cmdlet uses the Win32_PingStatus class. A "get-wmiobject win32_pingstatus" command is equivalent to a Test-Connection command. The Source parameter set was introduced in Windows PowerShell 3.0.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>Test-Connection Server01
Source Destination IPV4Address IPV6Address Bytes Time(ms)
------ ----------- ----------- ----------- ----- --------
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 1
This command sends echo request packets ("pings") from the local computer to the Server01 computer. This command uses the ComputerName parameter to specify the Server01 computer, but omits the optional parameter name. -------------------------- EXAMPLE 2 --------------------------
PS C:\>Test-Connection -ComputerName Server01, Server02, Server12
This command sends pings from the local computer to several remote computers. -------------------------- EXAMPLE 3 --------------------------
PS C:\>Test-Connection -Source Server02, Server12, localhost -ComputerName Server01 -Credential Domain01\Admin01
This command sends pings from different source computers to a single remote computer, Server01. It uses the Credential parameter to specify the credentials of a user who has permission to send a ping request from the source computers. Use this command format to test the latency of connections from multiple points. -------------------------- EXAMPLE 4 --------------------------
PS C:\>Test-Connection -ComputerName Server01 -Count 3 -Delay 2 -TTL 255 -BufferSize 256 -ThrottleLimit 32
This command sends three pings from the local computer to the Server01 computer. It uses the parameters of Test-Connection to customize the command. Use this command format when the ping response is expected to take longer than usual, either because of an extended number of hops or a high-traffic network condition. -------------------------- EXAMPLE 5 --------------------------
PS C:\>$job = Test-connection -ComputerName (Get-Content Servers.txt) -asjob
PS C:\>if ($job.JobStateInfo.State -ne "Running") {$Results = Receive-Job $job}
This example shows how to run a Test-Connection command as a Windows PowerShell background job. The first command uses the Test-Connection cmdlet to ping many computers in an enterprise. The value of the ComputerName parameter is a Get-Content command that reads a list of computer names from the Servers.txt file. The command uses the AsJob parameter to run the command as a background job and it saves the job in the $job variable. The second command checks to see that the job is not still running, and if it is not, it uses a Receive-Job command to get the results and store them in the $Results variable. -------------------------- EXAMPLE 6 --------------------------
PS C:\>Test-Connection Server55 -Credential Domain55\User01 -Impersonation Identify
This command uses the Test-Connection cmdlet to ping a remote computer. The command uses the Credential parameter to specify a user account with permission to ping the remote computer and the Impersonation parameter to change the impersonation level to "Identify". -------------------------- EXAMPLE 7 --------------------------
PS C:\>if (Test-Connection -ComputerName Server01 -Quiet) {New-PSSession Server01}
This command creates a session on the Server01 computer only if at least one of the pings sent to the computer succeeds. The command uses the Test-Connection cmdlet to ping the Server01 computer. The command uses the Quiet parameter, which returns a Boolean value, instead of a Win32_PingStatus object. The value is $True if any of the four pings succeed and is, otherwise, $False. If the Test-Connection command returns a value of $True, the command uses the New-PSSession cmdlet to create the PSSession.
###RELATED LINKS Online Version: Add-Computer Restart-Computer Stop-Computer ##Test-Path
###SYNOPSIS Determines whether all elements of a path exist.
###SYNTAX TODO
###DESCRIPTION The Test-Path cmdlet determines whether all elements of the path exist. It returns TRUE ($true) if all elements exist and FALSE ($false) if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal (leaf) element.
###PARAMETERS
####Credential [<PSCredential>]
Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with Windows PowerShell.
####Exclude [<String[]>]
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####Filter [<String>]
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.
####Include [<String[]>]
Tests only the specified paths. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
####IsValid [<SwitchParameter>]
Determines whether the syntax of the path is correct, regardless of whether the elements of the path exist. This parameter returns TRUE if the path syntax is valid and FALSE if it is not.
####LiteralPath <String[]>
Specifies a path to be tested. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
####Path <String[]>
Specifies a path to be tested. Wildcards are permitted. If the path includes spaces, enclose it in quotation marks. The parameter name ("Path") is optional.
####PathType [<TestPathType>]
Tells whether the final element in the path is of a particular type. This parameter returns TRUE if the element is of the specified type and FALSE if it is not. Valid values are: -- Container: An element that contains other elements, such as a directory or registry key. -- Leaf: An element that does not contain other elements, such as a file. -- Any: Either a container or a leaf. Tells whether the final element in the path is of a particular type. Returns TRUE if the element is of the specified type and FALSE if it is not.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####System.String You can pipe a string that contains a path (but not a literal path) to Test-Path.
###OUTPUTS ####System.Boolean The cmdlet returns "True" when the path exists and "False" when it does not.
###NOTES ####System.Boolean The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators. You can use the Path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers. The Test-Path cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>test-path -path "C:\Documents and Settings\NicoleH"
This command tells whether all elements in the path exist, that is, the C: directory, the Documents and Settings directory, and the NicoleH directory. If any are missing, the cmdlet returns FALSE. Otherwise, it returns TRUE.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>test-path -path $profile
PS C:\>test-path -path $profile -IsValid
These commands test the path to the Windows PowerShell profile. The first command determines whether all elements in the path exist. The second command determines whether the syntax of the path is correct. In this case, the path is FALSE, but the syntax is correct (TRUE). These commands use $profile, the automatic variable that points to the location for the profile, even if the profile does not exist. For more information about automatic variables, see about_Automatic_Variables.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>test-path -path "C:\CAD\Commercial Buildings\*" -exclude *.dwg
This command tells whether there are any files in the Commercial Buildings directory other than .dwg files. The command uses the Path parameter to specify the path. Because it includes a space, the path is enclosed in quotes. The asterisk at the end of the path indicates the contents of the Commercial Building directory. (With long paths, like this one, type the first few letters of the path, and then use the TAB key to complete the path.) The command uses the Exclude parameter to specify files that will be omitted from the evaluation. In this case, because the directory contains only .dwg files, the result is FALSE.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>test-path -path $profile -pathtype leaf
This command tells whether the path stored in the $profile variable leads to a file. In this case, because the Windows PowerShell profile is a .ps1 file, the cmdlet returns TRUE.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>test-path -path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
TRUE
PS C:\>test-path -path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy
FALSE
These commands use the Test-Path cmdlet with the Windows PowerShell registry provider. The first command tests whether the registry path to the Microsoft.PowerShell registry key is correct on the system. If Windows PowerShell is installed correctly, the cmdlet returns TRUE. Test-Path does not work correctly with all Windows PowerShell providers. For example, you can use Test-Path to test the path to a registry key, but if you use it to test the path to a registry entry, it always returns FALSE, even if the registry entry is present.
###RELATED LINKS Online Version: Convert-Path Join-Path Resolve-Path Split-Path about_Providers ##Undo-Transaction
###SYNOPSIS Rolls back the active transaction.
###SYNTAX TODO
###DESCRIPTION The Undo-Transaction cmdlet rolls back the active transaction. When you roll back a transaction, the changes made by the commands in the transaction are discarded and the data is restored to its original form. If the transaction includes multiple subscribers, an Undo-Transaction command rolls back the entire transaction for all subscribers. By default, transactions are rolled back automatically if any command in the transaction generates an error. However, transactions can be started with a different rollback preference and you can use this cmdlet to roll back the active transaction at any time. The Undo-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_Transactions.
###PARAMETERS
####Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
####WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####None This cmdlet does not return any output.
###NOTES ####None You cannot roll back a transaction that has been committed. You cannot roll back any transaction other than the active transaction. To roll back a different, independent transaction, you must first commit or roll back the active transaction. Rolling back the transaction ends the transaction. To use a transaction again, you must start a new transaction.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>undo-transaction
This command rolls back the current (active) transaction.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\Software> start-transaction
PS HKCU:\Software> new-item MyCompany -usetransaction
PS HKCU:\Software> undo-transaction
This command starts a transaction and then rolls it back. As a result, no changes are made to the registry.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>cd hkcu:\software
PS HKCU:\Software> start-transaction
PS HKCU:\Software> new-item MyCompany -usetransaction
PS HKCU:\Software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- -----
Error 1 Active
PS HKCU:\Software> start-transaction
PS HKCU:\Software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- -----
Error 2 Active
PS HKCU:\Software> undo-transaction
PS HKCU:\Software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- -----
Error 0 RolledBack
This example demonstrates that when any subscriber rolls back a transaction, the entire transaction is rolled back for all subscribers. The first command changes the location to the HKCU:\Software registry key. The second command starts a transaction. The third command uses the New-Item cmdlet to create a new registry key. The command uses the UseTransaction parameter to include the change in the transaction. The fourth command uses the Get-Transaction cmdlet to get the active transaction. Notice that the status is Active and the subscriber count is 1. The fifth command uses the Start-Transaction command again. Typically, starting a transaction while another transaction is in progress occurs when a script used by the main transaction includes its own complete transaction. (This example is done interactively so that you can examine it in stages.) When you enter a Start-Transaction command while another transaction is in progress, the commands join the existing transaction as a new "subscriber" and the subscriber count is incremented. The sixth command uses the Get-Transaction cmdlet to get the active transaction. Notice that the subscriber count is now 2. The seventh command uses the Undo-Transaction cmdlet to roll back the transaction. This command does not return any objects. The final command is a Get-Transaction command that gets the active (or in this case, the most recently active) transaction. The results show that the transaction is rolled back, and that the subscriber count is 0, showing that the transaction was rolled back for all subscribers.
###RELATED LINKS Online Version: Complete-Transaction Get-Transaction Start-Transaction Use-Transaction about_Providers about_Transactions ##Use-Transaction
###SYNOPSIS Adds the script block to the active transaction.
###SYNTAX TODO
###DESCRIPTION The Use-Transaction cmdlet adds a script block to an active transaction. This enables you to do transacted scripting using transaction-enabled Microsoft .NET Framework objects. The script block can contain only transaction-enabled .NET Framework objects, such as instances of the Microsoft.PowerShell.Commands.Management.TransactedString class. The UseTransaction parameter, which is optional for most cmdlets, is required when using this cmdlet. The Use-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_Transactions.
###PARAMETERS
####TransactedScript <ScriptBlock>
Specifies the script block that is run in the transaction. Enter any valid script block enclosed in braces ( { } ). This parameter is required.
####UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####PSObject Use-Transaction returns the result of the transaction.
###NOTES ####PSObject The Use-Transaction parameter includes the command in the active transaction. Because the Use-Transaction cmdlet is always used in transactions, this parameter is required to make any Use-Transaction command effective.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>start-transaction
PS C:\>$transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
PS C:\>$transactedString.Append("Hello")
PS C:\>use-transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
PS C:\>$transactedString.ToString()
Hello
PS C:\>use-transaction -transactedScript { $transactedString.ToString() } -UseTransaction
Hello, World
PS C:\>complete-transaction
PS C:\>$transactedString.ToString()
Hello, World
This example shows how to use the Use-Transaction cmdlet to script against a transaction-enabled .NET Framework object. In this case, the object is a TransactedString object. The first command uses the Start-Transaction cmdlet to start a transaction. The second command uses the New-Object command to create a TransactedString object. It stores the object in the $TransactedString variable. The third and fourth commands both use the Append method of the TransactedString object to add text to the value of $TransactedString. One command is part of the transaction; the other is not. The third command uses the Append method of the transacted string to add "Hello" to the value of $TransactedString. Because the command is not part of the transaction, the change is applied immediately. The fourth command uses the Use-Transaction cmdlet to add text to the string within the transaction. The command uses the Append method to add ", World" to the value of $TransactedString. The command is enclosed in braces ( {} ) to make it a script block. The UseTransaction parameter is required in this command. The fifth and sixth commands use the ToString method of the TransactedString object to display the value of the TransactedString as a string. Again, one command is part of the transaction; the other is not. The fifth command uses the ToString method to display the current value of the $TransactedString variable. Because it is not part of the transaction, it displays only the current state of the string. The sixth command uses the Use-Transaction cmdlet to run the same command within the transaction. Because the command is part of the transaction, it displays the current value of the string within the transaction, much like a preview of the transaction changes. The seventh command uses the Complete-Transaction cmdlet to commit the transaction. The final command uses the ToString method to display the resulting value of the variable as a string.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>start-transaction
PS C:\>$transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
PS C:\>$transactedString.Append("Hello")
PS C:\>use-transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
PS C:\>undo-transaction
PS C:\>$transactedString.ToString()
Hello
This example shows the effect of rolling back a transaction that includes Use-Transaction commands. Like all commands in a transaction, when the transaction is rolled back, the transacted changes are discarded and the data is unchanged. The first command uses the Start-Transaction cmdlet to start a transaction. The second command uses the New-Object command to create a TransactedString object. It stores the object in the $TransactedString variable. The third command, which is not part of the transaction, uses the Append method to add "Hello" to the value of $TransactedString. The fourth command uses the Use-Transaction cmdlet to run another command that uses the Append method within the transaction. The command uses the Append method to add ", World" to the value of $TransactedString. The fifth command uses the Undo-Transaction cmdlet to roll back the transaction. As a result, all commands performed within the transaction are reversed. The final command uses the ToString method to display the resulting value of $TransactedString as a string. The results show that only the changes made outside of the transaction were applied to the object.
###RELATED LINKS Online Version: Complete-Transaction Get-Transaction Start-Transaction Undo-Transaction about_Transactions ##Wait-Process
###SYNOPSIS Waits for the processes to be stopped before accepting more input.
###SYNTAX TODO
###DESCRIPTION The Wait-Process cmdlet waits for one or more running processes to be stopped before accepting input. In the Windows PowerShell console, this cmdlet suppresses the command prompt until the processes are stopped. You can specify a process by process name or process ID (PID), or pipe a process object to Wait-Process. Wait-Process works only on processes running on the local computer.
###PARAMETERS
####Id <Int32[]>
Specifies the process IDs of the processes. To specify multiple IDs, use commas to separate the IDs. To find the PID of a process, type "get-process". The parameter name ("Id") is optional.
####InputObject <Process[]>
Specifies the processes by submitting process objects. Enter a variable that contains the process objects, or type a command or expression that gets the process objects, such as a Get-Process command.
####Name <String[]>
Specifies the process names of the processes. To specify multiple names, use commas to separate the names. Wildcards are not supported.
####Timeout [<Int32>]
Determines the maximum time, in seconds, that Wait-Process waits for the specified processes to stop. When this interval expires, the command displays a non-terminating error that lists the processes that are still running, and ends the wait. By default, there is no timeout.
###INPUTS ####System.Diagnostics.Process You can pipe a process object to Wait-Process.
###OUTPUTS ####None This cmdlet does not generate any output.
###NOTES ####None This cmdlet uses the WaitForExit method of the System.Diagnostics.Process class. For more information about this method, see the Microsoft .NET Framework SDK.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>$nid = (get-process notepad).id
PS C:\>stop-process -id $nid
PS C:\>wait-process -id $nid
These commands stop the Notepad process and then wait for the process to be stopped before proceeding with the next command. The first command uses the Get-Process cmdlet to get the ID of the Notepad process. It saves it in the $nid variable. The second command uses the Stop-Process cmdlet to stop the process with the ID saved in $nid. The third command uses the Wait-Process cmdlet to wait until the Notepad process is stopped. It uses the ID parameter of Wait-Process to identify the process.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>$p = get-process notepad
PS C:\>wait-process -id $p.id
PS C:\>wait-process -name notepad
PS C:\>wait-process -inputobject $p
These commands show three different methods of specifying a process to the Wait-Process cmdlet. The first command gets the Notepad process and saves it in the $p variable. The second command uses the ID parameter, the third command uses the Name parameter, and the fourth command uses the InputObject parameter. These commands have the same results and can be used interchangeably.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>wait-process -name outlook, winword -timeout 30
This command waits 30 seconds for the Outlook and Winword processes to stop. If both processes are not stopped, the cmdlet displays a non-terminating error and the command prompt.
###RELATED LINKS Online Version: Debug-Process Get-Process Start-Process Stop-Process Wait-Process ##Write-EventLog
###SYNOPSIS Writes an event to an event log.
###SYNTAX TODO
###DESCRIPTION The Write-EventLog cmdlet writes an event to an event log. To write an event to an event log, the event log must exist on the computer and the source must be registered for the event log. The cmdlets that contain the EventLog noun (the EventLog cmdlets) work only on classic event logs. To get events from logs that use the Windows Event Log technology in Windows Vista and later versions of Windows, use Get-WinEvent.
###PARAMETERS
####Category [<Int16>]
Specifies a task category for the event. Enter an integer that is associated with the strings in the category message file for the event log.
####ComputerName [<String>]
Specifies a remote computer. The default is the local computer. Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of a remote computer. This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-EventLog even if your computer is not configured to run remote commands.
####EntryType [<EventLogEntryType>]
Specifies the entry type of the event. Valid values are Error, Warning, Information, SuccessAudit, and FailureAudit. The default value is Information. {For a description of the values, see System.Diagnostics.EventLogEntryType in the , at htt...
####EventId <Int32>
Specifies the event identifier. This parameter is required.
####LogName <String>
Specifies the name of the log to which the event is written. Enter the log name (the value of the Log property, not the LogDisplayName). Wildcard characters are not permitted. This parameter is required.
####Message <String>
Specifies the event message. This parameter is required.
####RawData [<Byte[]>]
Specifies the binary data that is associated with the event, in bytes.
####Source <String>
Specifies the event source, which is typically the name of the application that is writing the event to the log.
###INPUTS ####None You cannot pipe input to this cmdlet.
###OUTPUTS ####System.Diagnostics.EventLogEntry Write-EventLog returns objects that represents the events in the logs.
###NOTES ####System.Diagnostics.EventLogEntry To use Write-EventLog, start Windows PowerShell with the "Run as administrator" option.
###EXAMPLES -------------------------- EXAMPLE 1 --------------------------
PS C:\>write-eventlog -logname Application -source MyApp -eventID 3001 -entrytype Information -message "MyApp added a user-requested feature to the display." -category 1 -rawdata 10,20
This command writes an event from the MyApp source to the Application event log.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>write-eventlog -computername Server01 -logname Application -source MyApp -eventID 3001 -message "MyApp added a user-requested feature to the display."
This command writes an event from the MyApp source to the Application event log on the Server01 remote computer.
###RELATED LINKS Online Version: Clear-EventLog Get-EventLog Limit-EventLog New-EventLog Remove-EventLog Show-EventLog Write-EventLog