All posts by Adam

Use-Transaction

February 26, 2014 Adam

SYNOPSIS
Adds the script block to the active transaction.

SYNTAX
Use-Transaction [-TransactedScript] <scriptblock> [-UseTransaction] [<CommonParameters>]

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.

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

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
PSObject
Use-Transaction returns the result of the transaction.

NOTES

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.

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

C:\PS>Start-Transaction

C:\PS> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString

C:\PS> $transactedString.Append(“Hello”)
C:\PS> Use-Transaction -TransactedScript { $transactedString.Append(“, World”) } -UseTransaction

C:\PS> $transactedString.ToString()
Hello

C:\PS> Use-Transaction -TransactedScript { $transactedString.ToString() } -UseTransaction
Hello, World

    C:\PS> Complete-Transaction
    C:\PS> $transactedString.ToString()
    Hello, World

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

C:\PS>Start-Transaction

C:\PS> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString

C:\PS> $transactedString.Append(“Hello”)
C:\PS> Use-Transaction -TransactedScript { $transactedString.Append(“, World”) } -UseTransaction

C:\PS> Undo-Transaction

C:\PS> $transactedString.ToString()
Hello

    Description
    ———–
    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: http://go.microsoft.com/fwlink/?LinkID=135271
    about_transactions
    Start-Transaction
    Get-Transaction
    Complete-Transaction
    Undo-Transaction

cmdlet, TypeData, Update

Update-TypeData

February 26, 2014 Adam

NAME
Update-TypeData

SYNOPSIS
Updates the current extended type configuration by reloading the *.types.ps1xml files into memory.

SYNTAX
Update-TypeData [[-AppendPath] <string[]>] [-PrependPath <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Update-TypeData cmdlet updates the current extended type configuration by reloading the *.types.ps1xml files into memory. Extended type information is normally loaded when Windows PowerShell requires the type information it contains. The Update-TypeData cmdlet can be used to preload all type information. It is particularly useful when you are developing types and want to load those new types for testing purposes.

For more information about the *types.ps1xml files in Windows PowerShell, see about_types.ps1xml.

PARAMETERS
-AppendPath <string[]>
Specifies the path to the optional .ps1xml files that will be included in the list of files loaded. These are processed after the built-in files are loaded.

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

-PrependPath <string[]>
Specifies the path to the optional .ps1xml files that will be included in the list of files loaded. However, these files are processed in the order they are specified and before the built-in files are loaded.

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

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

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

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

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

INPUTS
System.String
You can pipe a string that contains the append path to Update-TypeData.

OUTPUTS
None
This cmdlet does not return any output.

NOTES

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

C:\PS>Update-TypeData

    Description
    ———–
    This example updates the extended type configuration from the *.types.ps1xml files.

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

C:\PS>Update-TypeData -PrependPath typesA.types.Ps1xml, typesB.types.Ps1xml

    Description
    ———–
    This example updates the extended type configuration from the *.types.ps1xml files, processing the typesA and typesB files first.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113421

cmdlet, List, Update

Update-List

February 26, 2014 Adam

NAME
Update-List

SYNOPSIS
Adds items to and removes items from a property value that contains a collection of objects.

SYNTAX
Update-List [-Add <Object[]>] [-Remove <Object[]>] [[-Property] <string>] [-InputObject <psobject>] [<CommonParameters>]

Update-List -Replace <Object[]> [[-Property] <string>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Update-List cmdlet adds items to and removes items from a property value of an object, and then it returns the updated object. This cmdlet is designed for properties that contain collections of objects.

The Add and Remove parameters add individual items to and remove them from the collection. The Replace parameter replaces the entire collection.

If you do not specify a property in the command, Update-List returns an object that describes the update instead of updating the object. You can submit the update object to cmdlets that change objects, such as Set-* cmdlets.

This cmdlet works only when the property that is being updated supports the IList interface that Update-List uses. Also, any Set-* cmdlets that accept an update must support the IList interface. The core cmdlets that are installed with Windows PowerShell do not support this interface. To determine whether a cmdlet supports Update-List, see the cmdlet Help topic.

PARAMETERS
-Add <Object[]>
Specifies the property values to be added to the collection. Enter the values in the order that they should appear in the collection.

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

-InputObject <psobject>
Specifies the objects to be updated. You can also pipe the object to be updated to Update-List.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Property <string>
Identifies the property that contains the collection that is being updated. If you omit this parameter, Update-List returns an object that represents the change instead of changing the object.

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

-Remove <Object[]>
Specifies the property values to be removed from the collection.

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

-Replace <Object[]>
Specifies a new collection. This parameter replaces all items in the original collection with the items specified by this parameter.

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

INPUTS
System.Management.Automation.PSObject
You can pipe the objects to be updated to Update-List.

OUTPUTS
Objects or System.Management.Automation.PSListModifier
Update-List returns the updated object, or it returns an object that represents the update action.

NOTES

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

C:\PS>get-mailbox | Update-List -Property Aliases -Add “A”,”B” -Remove “X”,”Y” | set-mailbox

    Description
    ———–
    This command adds A and B and removes X and Y from the Aliases property of a mailbox.

The command uses the Get-MailBox cmdlet from Microsoft Exchange Server to get the mailbox. A pipeline operator sends the mailbox object to the Update-List cmdlet.

The Update-List command uses the Property parameter to indicate that the Aliases property of the mailbox is being updated, and it uses the Add and Remove parameters to specify the items that are being added and removed from the collection. The Aliases property fulfills the conditions of Update-List, because it stores a collection of Microsoft .NET Framework objects that have Add and Remove methods.

The Update-List cmdlet returns the updated mailbox, which is piped to the Set-MailBox cmdlet, which changes the mailbox.

For more information about Get-Mailbox, see http://go.microsoft.com/fwlink/?LinkId=111536.

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

C:\PS>$m = get-mailbox

C:\PS> Update-List -InputObject $m -Property Aliases -Add “A”,”B” -Remove “X”, “Y” | set-mailbox

    Description
    ———–
    This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the previous command, although it has a slightly different format.

The command uses the Get-MailBox cmdlet to get the mailbox, and it saves the mailbox in the $m Variable. This command uses the InputObject parameter of Update-List to specify the mailbox. The value of InputObject is the mailbox in the $m Variable. It uses the Property parameter to specify the Aliases property and the Add and Remove parameters to specify the items being added to and removed from the value of Aliases.

The command uses a pipeline operator (|) to send the updated mailbox object to the Set-Mailbox cmdlet, which changes the mailbox.

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

C:\PS>get-mailbox | set-mailbox -alias (Update-List -Add “A”, “B” -Remove “X”,”Y”)

    Description
    ———–
    This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the two previous commands, but it uses a different procedure to perform the task.

Instead of updating the Aliases property of the mailbox before sending it to Set-Mailbox, this command uses Update-List to create an object that represents the change. Then it submits the change to the Alias parameter of Set-Mailbox.

The command uses the Get-MailBox cmdlet to get the mailbox. A pipeline operator sends the mailbox object to the Set-Mailbox cmdlet, which changes mailboxes.

The command uses the Alias parameter of Set-Mailbox to change the Aliases property of the mailbox object. The value of the Alias parameter is an Update-List command that creates an object that represents the update. The Update-List command is enclosed in parentheses to ensure that it runs before the value of the Alias parameter is evaluated. When the Set-Mailbox command completes, the mailbox is changed.

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

C:\PS>Update-List -InputObject $a -Property Aliases -replace “A”, “B” | set-mailbox

    Description
    ———–
    This command uses the Replace operator of Update-List to replace the collection in the Aliases property of the object in $a with a new collection.

This command uses the InputObject parameter which, in this case, is equivalent to using a pipeline operator to pass $a to Update-List.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113447
Select-Object

cmdlet, FormatData, Update

Update-FormatData

February 26, 2014 Adam

NAME
Update-FormatData

SYNOPSIS
Updates the formatting data in the current session.

SYNTAX
Update-FormatData [[-AppendPath] <string[]>] [-PrependPath <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Update-FormatData cmdlet reloads the formatting data from formatting files into the current session. This cmdlet lets you update the formatting data without restarting Windows PowerShell.

Without parameters, Update-FormatData reloads the formatting files that it loaded previously. You can use the parameters of Update-FormatData to add new formatting files to the session.

Formatting files are text files in XML format with the format.ps1xml file name extension. The formatting data in the files defines the display of Microsoft .NET Framework objects in the session.

When Windows PowerShell starts, it loads the format data from the formatting files in the Windows PowerShell installation directory ($pshome) into the session. You can use Update-FormatData to reload the formatting data into the current session without restarting Windows PowerShell. This is useful when you have added or changed a formatting file, but do not want to interrupt the session.

For more information about formatting files in Windows PowerShell, see about_Format.ps1xml.

PARAMETERS
-AppendPath <string[]>
Adds the specified formatting files to the session. The files are loaded after Windows PowerShell loads the built-in formatting files.

When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.

Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.

-PrependPath <string[]>
Adds the specified formatting files to the session. The files are loaded before Windows PowerShell loads the built-in formatting files.

When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the PrependPath parameter, Windows PowerShell searches the data from the files that you are adding before it encounters the formatting data from the built-in files.

Use this parameter to add a file that formats a .NET object that is also referenced in the built-in formatting files.

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

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

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

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

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

INPUTS
System.String
You can pipe a string that contains the append path to Update-FormatData.

OUTPUTS
None
The cmdlet does not return any output.

NOTES

Update-FormatData also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an Update-FormatData command to update the formatting data for imported commands. You do not need to import the module again.

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

C:\PS>Update-FormatData

    Description
    ———–
    This command reloads the formatting files that it loaded previously.

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

C:\PS>Update-FormatData -AppendPath trace.format.ps1xml, log.format.ps1xml

    Description
    ———–
    This command reloads the formatting files into the session, including two new files, Trace.format.ps1xml and Log.format.ps1xml.

Because the command uses the AppendPath parameter, the formatting data in the new files is loaded after the formatting data from the built-in files.

The AppendPath parameter is used because the new files contain formatting data for objects that are not referenced in the built-in files.

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

C:\PS>Update-FormatData -PrependPath c:\test\NewFiles.format.ps1xml

# Edit the NewFiles.format.ps1 file.

C:\PS> Update-FormatData

    Description
    ———–
    This example shows how to reload a formatting file after you have edited it.

The first command adds the NewFiles.format.ps1xml file to the session. It uses the PrependPath parameter because the file contains formatting data for objects that are referenced in the built-in files.

After adding the NewFiles.format.ps1xml file and testing it in these session, the author edits the file.

The second command uses the Update-FormatData cmdlet to reload the formatting files. Because the NewFiles.format.ps1xml file was previously loaded, Update-FormatData automatically reloads it without using parameters.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113420

cmdlet, PSSessionConfiguration, Unregister

Unregister-PSSessionConfiguration

February 26, 2014 Adam

NAME
Unregister-PSSessionConfiguration

SYNOPSIS
Deletes registered session configurations from the computer.

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

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

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

PARAMETERS
-Force [<SwitchParameter>]
Suppresses all user prompts, and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective.

To prevent a restart and suppress the restart prompt, use the NoServiceRestart parameter.

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

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

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

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

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

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

To restart the WinRM service without prompting, use the Force parameter. To restart the WinRM service manually, use the Restart-Service cmdlet.

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

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

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

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

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

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

OUTPUTS
None
This cmdlet does not return any objects.

NOTES

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

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

C:\PS>Unregister-PSSessionConfiguration -Name MaintenanceShell

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

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

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

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

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

C:\PS>Unregister-PSSessionConfiguration -Name *

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

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

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

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

C:\PS> Get-PSSessionConfiguration -Name maintenanceShell

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

C:\PS> New-PSSession -configurationName MaintenanceShell

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

C:\PS> Restart-Service winrm

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

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

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

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

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

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

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

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

cmdlet, Event, Unregister

Unregister-Event

February 26, 2014 Adam

NAME
Unregister-Event

SYNOPSIS
Cancels an event subscription.

SYNTAX
Unregister-Event [-SubscriptionId] <int> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Unregister-Event [-SourceIdentifier] <string> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Unregister-Event cmdlet cancels an event subscription that was created by using the Register-EngineEvent, Register-ObjectEvent, or Register-WmiEvent cmdlet.

When an event subscription is canceled, the event subscriber is deleted from the session and the subscribed events are no longer added to the event queue. When you cancel a subscription to an event created by using the New-Event cmdlet, the new event is also deleted from the session.

Unregister-Event does not delete events from the event queue. To delete events, use the Remove-Event cmdlet.

PARAMETERS
-Force [<SwitchParameter>]
Cancels all event subscriptions, including subscriptions that were hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.

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

-SourceIdentifier <string>
Cancels event subscriptions that have the specified source identifier.

A SourceIdentifier or SubscriptionId parameter must be included in every command.

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

-SubscriptionId <int>
Cancels event subscriptions that have the specified subscription identifier.

A SourceIdentifier or SubscriptionId parameter must be included in every command.

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

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

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

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

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

INPUTS
System.Management.Automation.PSEventSubscriber
You can pipe the output from Get-EventSubscriber to Unregister-Event.

OUTPUTS
None
This cmdlet does not return any output.

NOTES

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.

Unregister-Event cannot delete events created by using the New-Event cmdlet unless you have subscribed to the event by using the Register-EngineEvent cmdlet. To delete a custom event from the session, you must remove it programmatically or close the session.

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

C:\PS>Unregister-Event -SourceIdentifier ProcessStarted

    Description
    ———–
    This command cancels the event subscription that has a source identifier of “ProcessStarted”.

To find the source identifier of an event, use the Get-Event cmdlet. To find the source identifier of an event subscription, use the Get-EventSubscriber cmdlet.

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

C:\PS>Unregister-Event -subscriptionId 2

    Description
    ———–
    This command cancels the event subscription that has a subscription identifier of 2.

To find the subscription identifier of an event subscription, use the Get-EventSubscriber cmdlet.

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

C:\PS>Get-Eventsubscriber -Force | Unregister-Event -Force

    Description
    ———–
    This command cancels all event subscriptions in the session.

The command uses the Get-EventSubscriber cmdlet to get all event subscriber objects in the session, including the subscribers that are hidden by using the SupportEvent parameter of the event registration cmdlets.

It uses a pipeline operator (|) to send the subscriber objects to Unregister-Event, which deletes them from the session. To complete the task, the Force parameter is also required on Unregister-Event.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135269
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    Get-Event
    New-Event
    Remove-Event
    Wait-Event
    Get-EventSubscriber

cmdlet, Transaction, Undo

Undo-Transaction

February 26, 2014 Adam

NAME
Undo-Transaction

SYNOPSIS
Rolls back the active transaction.

SYNTAX
Undo-Transaction [-Confirm] [-WhatIf] [<CommonParameters>]

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 executing the command.

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

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

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
None
This cmdlet does not return any output.

NOTES

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.

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

C:\PS>Undo-Transaction

    Description
    ———–
    This command rolls back the current (active) transaction.

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

C:\PS>cd hkcu:\software

    PS HKCU:\Software> Start-Transaction
    PS HKCU:\Software> New-Item MyCompany -usetransaction
    PS HKCU:\Software> Undo-Transaction

    Description
    ———–
    This command starts a transaction and then rolls it back. As a result, no changes are made to the Registry.

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

C:\PS>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

    Description
    ———–
    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: http://go.microsoft.com/fwlink/?LinkID=135268
    about_transactions
    about_providers
    Start-Transaction
    Get-Transaction
    Complete-Transaction
    Use-Transaction

cmdlet, Command, Trace

Trace-Command

February 26, 2014 Adam

NAME
Trace-Command

SYNOPSIS
Configures and starts a trace of the specified expression or command.

SYNTAX
Trace-Command [-Command] <string> [-ArgumentList <Object[]>] [-Name] <string[]> [[-Option] {None | Constructor | Dispose | Finalizer | Method | Property | Delegates | Events | Exception | Lock | Error | Errors | Warning | Verbose | WriteLine | Data | Scope | ExecutionFlow | Assert | All}] [-Debugger] [-FilePath <string>] [-Force] [-InputObject <psobject>] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PSHost] [<CommonParameters>]

Trace-Command [-Expression] <scriptblock> [-Name] <string[]> [[-Option] {None | Constructor | Dispose | Finalizer | Method | Property | Delegates | Events | Exception | Lock | Error | Errors | Warning | Verbose | WriteLine | Data | Scope | ExecutionFlow | Assert | All}] [-Debugger] [-FilePath <string>] [-Force] [-InputObject <psobject>] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PSHost] [<CommonParameters>]

DESCRIPTION
The Trace-Command cmdlet configures and starts a trace of the specified expression or command. It works like Set-TraceSource, except that it applies only to the specified command.

PARAMETERS
-ArgumentList <Object[]>
Specifies the parameters and parameter values for the command being traced. The Alias for ArgumentList is Args. This feature is especially useful for debugging dynamic parameters.

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

-Command <string>
Specifies a command that is being processed during the trace.

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

-Debugger [<SwitchParameter>]
Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Visual Studio. This parameter also selects the default trace listener.

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

-Expression <scriptblock>
Specifies the expression that is being processed during the trace. Enclose the expression in curly braces ({}).

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

-FilePath <string>
Sends the trace output to the specified file. This parameter also selects the file trace listener.

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

-Force [<SwitchParameter>]
Allows the cmdlet to append trace information to a read-only file. Used with the FilePath parameter. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

-InputObject <psobject>
Provides input to the expression that is being processed during the trace.

You can enter a Variable that represents the input that the expression accepts, or pass an object through the pipeline.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-ListenerOption <TraceOptions>
Adds optional data to the prefix of each trace message in the output. The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. “None” is the default.

To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as “ProcessID,ThreadID”.

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

-Name <string[]>
Determines which Windows PowerShell components are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type “Get-TraceSource“.

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

-Option <PSTraceSourceOptions>
Determines the type of events that are traced.

The valid values are None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. “All” is the default.

The following values are combinations of other values:

— ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)

— Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)

— Errors: (Error and Exception).

To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as “Constructor,Dispose”.

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

-PSHost [<SwitchParameter>]
Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.

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

INPUTS
System.Management.Automation.PSObject
You can pipe objects that represent input to the expression to Trace-Command.

OUTPUTS
System.Management.Automation.PSObject
Returns the command trace in the debug stream.

NOTES

Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing.

The Windows PowerShell tracing cmdlets are designed to help Windows PowerShell developers, but they are available to all users. They let you monitor nearly every aspect of the Functionality of the shell.

To find the Windows PowerShell components that are enabled for tracing, type “Get-Help Get-TraceSource.”

A “trace source” is the part of each Windows PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.

A “trace listener” receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the host or console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

When you use the Command parameter set, Windows PowerShell processes the command just as it would be processed in a pipeline. For example, command discovery is not repeated for each incoming object.

The names of the Name, Expression, Option, and Command parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Name, Expression, Option or Name, Command,-Option . If you include the parameter names, the parameters can appear in any order.

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

C:\PS>Trace-Command -Name metadata,parameterbinding,cmdlet -Expression {Get-Process notepad} -PSHost

    Description
    ———–
    This command starts a trace of metadata processing, parameter binding, and cmdlet creation and destruction of the “Get-Process notepad” expression. It uses the Name parameter to specify the trace sources, the Expression parameter to specify the command, and the PSHost parameter to send the output to the console. Because it does not specify any tracing options or listener options, the command uses the defaults, “All” for the tracing options, and “None” for the listener options.

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

C:\PS>Trace-Command -Name commandprocessor,pipelineprocessor -command Get-Alias -argumentlist “ghy” -Option executionflow -ListenerOption “timestamp,callstack” -FilePath c:\test\debug.txt

    Description
    ———–
    This command starts a trace of the command processor and pipeline processor while processing the “Get-Alias cd” command.

It uses the Name parameter to specify the trace sources, the Command parameter to specify the command, the ArgumentList parameter to specify the parameters of the Get-Alias command, the Option parameter to specify tracing options, and the ListenerOption parameter to specify the fields in the trace message prefix. The FilePath parameter sends the output to the C:\Test\Debug.txt file.

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

C:\PS>$a = “i*”

C:\PS> Trace-Command parameterbinding {Get-Alias $input} -PSHost -InputObject $a

    Description
    ———–
    These commands trace the actions of the ParameterBinding operations of Windows PowerShell while it processes a Get-Alias expression that takes input from the pipeline.

In Trace-Command, the InputObject parameter passes an object to the expression that is being processed during the trace.

The first command stores the string “i*” in the $a Variable. The second command uses the Trace-Command cmdlet with the ParameterBinding trace source. The PSHost parameter sends the output to the console.

The expression being processed is “Get-Alias $input”, where the $input Variable is associated with the InputObject parameter. The InputObject parameter passes the Variable $a to the expression. In effect, the command being processed during the trace is “Get-Alias -InputObject $a” or “$a | Get-Alias“.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113419
    Get-TraceSource
    Set-TraceSource

cmdlet, Test, WSMan

Test-WSMan

February 26, 2014 Adam

NAME
Test-WSMan

SYNOPSIS
Tests whether the WinRM service is running on a local or remote computer.

SYNTAX
Test-WSMan [[-ComputerName] <string>] [-Authentication <Authentication>] [-Credential <PSCredential>] [<CommonParameters>]

DESCRIPTION
The Test-WSMan cmdlet submits an identification request that determines whether the WinRM service is running on a local or remote computer. If the tested computer is running the service, the cmdlet displays the WS-Management identity schema, the protocol version, the product vendor, and the product version of the tested service.

PARAMETERS
    -Authentication <Authentication>
        Specifies the authentication mechanism to be used at the server. Possible values are:
        – Basic: Basic is a scheme in which the user name and password are sent in clear text to the server or proxy.
        – Default : Use the authentication method implemented by the WS-Management protocol.
        – Digest: Digest is a challenge-response scheme that uses a server-specified data string for the challenge.
        – Kerberos: The client computer and the server mutually authenticate by using Kerberos Certificates.
        – Negotiate: Negotiate is a challenge-response scheme that negotiates with the server or proxy to determine the scheme to use for authentication. For example, this parameter value allows negotiation to determine whether the Kerberos protocol or NTLM is used.
        – CredSSP: Use Credential Security Service Provider (CredSSP) authentication, which allows the user to delegate credentials. This option is designed for commands that run on one remote computer but collect data from or run additional commands on other remote computers.

Caution: CredSSP delegates the user’s credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session.

Important: If the authentication parameter is not specified, then the Test-WSMan request will be sent to the remote machine anonymously (without using authentication). If the Test-WSMan request is made anonymously, it does not return any information that is specific to the operating-system version. Instead, Test-WSMan displays null values for the operating system version and service pack level (OS: 0.0.0 SP: 0.0).

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

-ComputerName <string>
Specifies the computer against which you want to run the management operation. The value can be a fully qualified domain name, a NetBIOS name, or an IP address. Use the local computer name, use localhost, or use a dot (.) to specify the local computer. The local computer is the default. When the remote computer is in a different domain from the user, you must use a fully qualified domain name must be used.

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

-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 User@Domain.com. Or, enter a PSCredential object, such as one returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.

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

INPUTS
None
This cmdlet does not accept any input.

OUTPUTS
None
This cmdlet does not generate any output object.

NOTES

By default, the Test-WSMan cmdlet queries the WinRM service without using authentication, and it does not return any information that is specific to the operating-system version. Instead, it displays null values for the operating system version and service pack level (OS: 0.0.0 SP: 0.0).

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

C:\PS>Test-WSMan

    wsmid         : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
    ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
    ProductVendor : Microsoft Corporation
    ProductVersion : OS: 0.0.0 SP: 0.0 Stack: 2.0

    Description
    ———–
    This command determines whether the WinRM service is running on the local computer or on a remote computer.

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

C:\PS>Test-WSMan -ComputerName server01

    Description
    ———–
    This command determines whether the WinRM service is running on the server01 computer named.

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

C:\PS>Test-WSMan -Authentication default

    Description
    ———–
    This command tests to see if the WS-Management (WinRM) service is running on the local computer using the authentication parameter.

Using the authentication parameter allows the Test-WSMan cmdlet to return the Operating System version.

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

C:\PS>Test-WSMan -ComputerName server01 -Authentication default

    Description
    ———–
    This command tests to see if the WS-Management (WinRM) service is running on the computer named server01 using the authentication parameter.

Using the authentication parameter allows the Test-WSMan cmdlet to return the operating system version.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkId=141464
    Connect-WSMan
    Disable-WSManCredSSP
    Disconnect-WSMan
    Enable-WSManCredSSP
    Get-WSManCredSSP
    Get-WSManInstance
    Invoke-WSManAction
    New-WSManInstance
    New-WSManSessionOption
    Remove-WSManInstance
    Set-WSManInstance
    Set-WSManQuickConfig

cmdlet, Path, Test

Test-Path

February 26, 2014 Adam

NAME
Test-Path

SYNOPSIS
Determines whether all elements of a path exist.

SYNTAX
Test-Path [-LiteralPath] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-IsValid] [-PathType {Any | Container | Leaf}] [-UseTransaction] [<CommonParameters>]

Test-Path [-Path] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-IsValid] [-PathType {Any | Container | Leaf}] [-UseTransaction] [<CommonParameters>]

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

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

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.

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

C:\PS>Test-Path -Path “C:\Documents and Settings\NicoleH”

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

C:\PS>Test-Path -Path $profile

C:\PS>Test-Path -Path $profile -IsValid

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

C:\PS>Test-Path -Path “C:\CAD\Commercial Buildings\*” -Exclude *.dwg

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

C:\PS>Test-Path -Path $profile -Pathtype leaf

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

C:\PS>Test-Path -Path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell

TRUE

C:\PS> Test-Path -Path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy
FALSE

    Description
    ———–
    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: http://go.microsoft.com/fwlink/?LinkID=113418
    about_providers
    Convert-Path
    Split-Path
    Resolve-Path
    Join-Path