TOPIC about_Transactions SHORT DESCRIPTION Describes how to manage transacted operations in Windows PowerShell. LONG DESCRIPTION Transactions are supported in Windows PowerShell beginning in Windows PowerShell 2.0. This feature enables you to start a transaction, to indicate which commands are part of the transaction, and to commit or roll back a transaction. ABOUT TRANSACTIONS In Windows PowerShell, a transaction is a set of one or more commands that are managed as a logical unit. A transaction can be completed ("committed"), which changes data affected by the transaction. Or, a transaction can be completely undone ("rolled back") so that the affected data is not changed by the transaction. Because the commands in a transaction are managed as a unit, either all commands are committed, or all commands are rolled back. Transactions are widely used in data processing, most notably in database operations and for financial transactions. Transactions are most often used when the worst-case scenario for a set of commands is not that they all fail, but that some commands succeed while others fail, leaving the system in a damaged, false, or uninterpretable state that is difficult to repair. TRANSACTION CMDLETS Windows PowerShell includes several cmdlets designed for managing transactions. Cmdlet Description -------------- --------------------------------- Start-Transaction Starts a new transaction. Use-Transaction Adds a command or expression to the transaction. The command must use transaction-enabled objects. Undo-Transaction Rolls back the transaction so that no data is changed by the transaction. Complete-Transaction Commits the transaction. The data affected by the transaction is changed. Get-Transaction Gets information about the active transaction. For a list of transaction cmdlets, type: get-command *transaction For detailed information about the cmdlets, type: get-help <cmdlet-name> -detailed For example: get-help use-transaction -detailed TRANSACTION-ENABLED ELEMENTS To participate in a transaction, both the cmdlet and the provider must support transactions. This feature is built in to the objects that are affected by the transaction. The Windows PowerShell Registry provider supports transactions in Windows Vista. The TransactedString object (Microsoft.PowerShell.Commands.Management.TransactedString) works with any operating system that runs Windows PowerShell. Other Windows PowerShell providers can support transactions. To find the Windows PowerShell providers in your session that support transactions, use the following command to find the "Transactions" value in the Capabilities property of providers: get-psprovider | where {$_.Capabilities -like "*transactions*"} For more information about a provider, see the Help for the provider. To get provider Help, type: get-help <provider-name> For example, to get Help for the Registry provider, type: get-help registry THE USETRANSACTION PARAMETER Cmdlets that can support transactions have a UseTransaction parameter. This parameter includes the command in the active transaction. You can use the full parameter name or its alias, "usetx". The parameter can be used only when the session contains an active transaction. If you enter a command with the UseTransaction parameter when there is no active transaction, the command fails. To find cmdlets with the UseTransaction parameter, type: get-help * -parameter UseTransaction In Windows PowerShell core, all of the cmdlets designed to work with Windows PowerShell providers support transactions. As a result, you can use the provider cmdlets to manage transactions. For more information about Windows PowerShell providers, see about_Providers. THE TRANSACTION OBJECT Transactions are represented in Windows PowerShell by a transaction object, System.Management.Automation.Transaction. The object has the following properties: RollbackPreference: Contains the rollback preference set for the current transaction. You can set the rollback preference when you use Start-Transaction to start the transaction. The rollback preference determines the conditions under which the transaction is rolled back automatically. Valid values are Error, TerminatingError, and Never. The default value is Error. Status: Contains the current status of the transaction. Valid values are Active, Committed, and RolledBack. SubscriberCount: Contains the number of subscribers to the transaction. A subscriber is added to a transaction when you start a transaction while another transaction is in progress. The subscriber count is decremented when a subscriber commits the transaction. ACTIVE TRANSACTIONS In Windows PowerShell, only one transaction is active at a time, and you can manage only the active transaction. Multiple transactions can be in progress in the same session at the same time, but only the most-recently started transaction is active. As a result, you cannot specify a particular transaction when using the transaction cmdlets. Commands always apply to the active transaction. This is most evident in the behavior of the Get-Transaction cmdlet. When you enter a Get-Transaction command, Get-Transaction always gets only one transaction object. This object is the object that represents the active transaction. To manage a different transaction, you must first finish the active transaction, either by committing it or rolling it back. When you do this, the previous transaction becomes active automatically. Transactions become active in the reverse of order of which they are started, so that the most recently started transaction is always active. SUBSCRIBERS AND INDEPENDENT TRANSACTIONS If you start a transaction while another transaction is in progress, by default, Windows PowerShell does not start a new transaction. Instead, it adds a "subscriber" to the current transaction. When a transaction has multiple subscribers, a single Undo-Transaction command at any point rolls back the entire transaction for all subscribers. However, to commit the transaction, you must enter a Complete-Transaction command for every subscriber. To find the number of subscribers to a transaction, check the SubscriberCount property of the transaction object. For example, the following command uses the Get-Transaction cmdlet to get the value of the SubscriberCount property of the active transaction: (Get-Transaction).SubscriberCount Adding a subscriber is the default behavior because most transactions that are started while another transaction is in progress are related to the original transaction. In the typical model, a script that contains a transaction calls a helper script that contains its own transaction. Because the transactions are related, they should be rolled back or committed as a unit. However, you can start a transaction that is independent of the current transaction by using the Independent parameter of the Start-Transaction cmdlet. When you start an independent transaction, Start-Transaction creates a new transaction object, and the new transaction becomes the active transaction. The independent transaction can be committed or rolled back without affecting the original transaction. When the independent transaction is finished (committed or rolled back), the original transaction becomes the active transaction again. CHANGING DATA When you use transactions to change data, the data that is affected by the transaction is not changed until you commit the transaction. However, the same data can be changed by commands that are not part of the transaction. Keep this in mind when you are using transactions to manage shared data. Typically, databases have mechanisms that lock the data while you are working on it, preventing other users, and other commands, scripts, and functions, from changing it. However, the lock is a feature of the database. It is not related to transactions. If you are working in a transaction-enabled file system or other data store, the data can be changed while the transaction is in progress. EXAMPLES The examples in this section use the Windows PowerShell Registry provider and assume that you are familiar with it. For information about the Registry provider, type "get-help registry". EXAMPLE 1: COMMITTING A TRANSACTION To create a transaction, use the Start-Transaction cmdlet. The ...
magdula294