This is the built-in help made by Microsoft for the command 'Use-Transaction', in PowerShell version 2 - as retrieved from
Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-23.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
Adds the script block to the active transaction.
Use-Transaction [-TransactedScript] <scriptblock> [-UseTransaction] [<CommonParameters>]
The Use-Transaction cmdlet adds a script block to an active transaction. This enables you to do transacted scripting using transaction-enabled Mi
crosoft .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 abou
t_Transactions.
<
Online version: http://go.microsoft.com/fwlink/?LinkID=135271
about_Transactions
Start-Transaction
Get-Transaction
Complete-Transaction
Undo-Transaction
<
-------------------------- 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 comman
d 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 pa
rt 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 re
quired 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. Aga
in, 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 transact
ion, 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 th
e 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 r
eversed.
The final command uses the ToString method to display the resulting value of $TransactedString as a string. The results show that only the change
s made outside of the transaction were applied to the object.