About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers
 

about_Transactions

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 
    following command starts a transaction with the default settings. 
  
 start-transaction 
 
    To include commands in the transaction, use the UseTransaction 
    parameter of the cmdlet. By default, commands are not included 
    in the transaction,        
 
    For example, the following command, which sets the current  
    location in the Software key of the HKCU: drive, is not included 
    in the transaction. 
 
        cd hkcu:\Software 
 
    The following command, which creates the MyCompany key, uses the 
    UseTransaction parameter of the New-Item cmdlet to include the 
    command in the active transaction. 
 
        new-item MyCompany -UseTransaction 
 
    The command returns an object that represents the new key, but 
    because the command is part of the transaction, the registry 
    is not yet changed. 
 
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
          0   0 MyCompany                      {} 
 
 
    To commit the transaction, use the Complete-Transaction cmdlet. 
    Because it always affects the active transaction, you cannot specify 
    the transaction. 
 
complete-transaction     
 
 
    As a result, the MyCompany key is added to the registry. 
 
dir m* 
        
        Hive: HKEY_CURRENT_USER\software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
         83   1 Microsoft                      {(default)} 
          0   0 MyCompany                      {} 
  
 
 

EXAMPLE 2: ROLLING BACK A TRANSACTION

 
    To create a transaction, use the Start-Transaction cmdlet. The 
    following command starts a transaction with the default settings. 
  
 start-transaction 
 
    The following command, which creates the MyOtherCompany key, uses the 
    UseTransaction parameter of the New-Item cmdlet to include the 
    command in the active transaction. 
 
        new-item MyOtherCompany -UseTransaction 
 
    The command returns an object that represents the new key, but 
    because the command is part of the transaction, the registry 
    is not yet changed. 
 
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
          0   0 MyOtherCompany                 {} 
 
 
    To roll back the transaction, use the Undo-Transaction cmdlet. 
    Because it always affects the active transaction, you do not specify 
    the transaction. 
 
Undo-transaction     
 
    The result is that the MyOtherCompany key is not added to the registry. 
 
dir m* 
        
        Hive: HKEY_CURRENT_USER\software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
         83   1 Microsoft                      {(default)} 
          0   0 MyCompany                      {} 
 
 
  

EXAMPLE 3: PREVIEWING A TRANSACTION

 
    Typically, the commands used in a transaction change data. However, 
    the commands that get data are useful in a transaction, too, because 
    they get data inside of the transaction. This provides a preview of the  
    changes that committing the transaction would cause. 
 
    The following example shows how to use the Get-ChildItem command 
    (the alias is "dir") to preview the changes in a transaction. 
 
 
    The following command starts a transaction. 
 
start-transaction 
 
    The following command uses the New-ItemProperty cmdlet to add the 
    MyKey registry entry to the MyCompany key. The command uses the 
    UseTransaction parameter to include the command in the transaction. 
 
 
        new-itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction 
 
    The command returns an object representing the new registry entry, 
    but the registry entry is not changed. 
 
        MyKey 
        ----- 
        123 
 
 
    To get the items that are currently in the registry, use a Get-ChildItem 
    command ("dir") without the UseTransaction parameter. The following  
    command gets items that begin with "M." 
 
dir m* 
 
 
    The result shows that no entries have yet been added to the MyCompany key. 
 
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
        83   1 Microsoft                      {(default)} 
         0   0 MyCompany                      {} 
 
 
    To preview the effect of committing the transaction, enter a Get-ChildItem 
    ("dir") command with the UseTransaction parameter. This command has a view 
    of the data from within the transaction. 
 
 
dir m* -useTransaction 
 
 
    The result shows that, if the transaction is committed, the MyKey entry 
    will be added to the MyCompany key. 
 
 
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
        83   1 Microsoft                      {(default)} 
         0   1 MyCompany                      {MyKey} 
 
 
      

EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS

 
    You can enter non-transacted commands during a transaction. The 
    non-transacted commands affect the data immediately, but they do 
    not affect the transaction. 
 
    The following command starts a transaction in the HKCU:\Software 
    registry key. 
 
start-transaction 
 
 
    The next three commands use the New-Item cmdlet to add keys to 
    the registry. The first and third commands use the UseTransaction 
    parameter to include the commands in the transaction. The second 
    command omits the parameter. Because the second command is not 
    included in the transaction, it is effective immediately. 
 
        new-item MyCompany1 -UseTransaction 
 
        new-item MyCompany2 
 
        new-item MyCompany3 -UseTransaction 
 
 
    To view the current state of the registry, use a Get-ChildItem ("dir") 
    command without the UseTransaction parameter. This command gets items 
    that begin with "M." 
 
dir m* 
 
    The result shows that the MyCompany2 key is added to the registry, but 
    the MyCompany1 and MyCompany3 keys, which are part of the transaction, 
    are not added. 
      
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
        83   1 Microsoft                      {(default)} 
        0    0 MyCompany2                     {} 
 
 
    The following command commits the transaction.  
 
        complete-transaction 
 
    Now, the keys that were added as part of the transaction appear in the 
    registry. 
 
dir m* 
 
      
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
        83   1 Microsoft                      {(default)} 
        0    0 MyCompany1                     {} 
        0    0 MyCompany2                     {} 
        0    0 MyCompany3                     {} 
 
 
 

EXAMPLE 5: USING AUTOMATIC ROLLBACK

 
    When a command in a transaction generates an error 
    of any kind, the transaction is automatically rolled 
    back.  
 
    This default behavior is designed for scripts that 
    run transactions. Scripts are typically well tested 
    and include error-handling logic, so errors are not 
    expected and should terminate the transaction.  
 
    The first command starts a transaction in the HKCU:\Software 
    registry key. 
 
start-transaction 
 
    The following command uses the New-Item cmdlet to 
    add the MyCompany key to the registry. The command uses 
    the UseTransaction parameter (the alias is "usetx") to include 
    the command in the transaction. 
 
New-Item MyCompany -UseTX 
 
    Because the MyCompany key already exists in the registry, 
    the command fails, and the transaction is rolled back.         
 
        New-Item : A key at this path already exists 
        At line:1 char:9 
        + new-item <<<<  MyCompany -usetx 
 
    A Get-Transaction command confirms that the transaction 
    has been rolled back and that the SubscriberCount is 0. 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                0                 RolledBack  
 
         

EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE

 
    If you want the transaction to be more error tolerant, 
    you can use the RollbackPreference parameter of  
    Start-Transaction to change the preference. 
 
    The following command starts a transaction with a 
    rollback preference of "Never". 
 
         start-transaction -rollbackpreference Never 
 
    In this case, when the command fails, the transaction 
    is not automatically rolled back. 
 
New-Item MyCompany -UseTX 
 
        New-Item : A key at this path already exists 
        At line:1 char:9 
        + new-item <<<<  MyCompany -usetx 
    
      
    Because the transaction is still active, you can 
    resubmit the command as part of the transaction.  
 
New-Item MyOtherCompany -UseTX 
 
 
 

EXAMPLE 7: USING THE USE-TRANSACTION CMDLET

 
    The Use-Transaction cmdlet enables you to do direct scripting 
    against transaction-enabled Microsoft .NET Framework  objects. 
    Use-Transaction takes a script block that can only contain commands 
    and expressions that use transaction-enabled .NET Framework objects, 
    such as instances of the  
    Microsoft.PowerShell.Commands.Management.TransactedString class. 
 
    The following command starts a transaction. 
 
         start-transaction 
 
    The following New-Object command creates an instance of the 
    TransactedString class and saves it in the $t variable. 
 
         $t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString 
 
    The following command uses the Append method of the TransactedString 
    object to add text to the string. Because the command is not part 
    of the transaction, the change is effective immediately. 
 
 $t.append("Windows")  
 
    The following command uses the same Append method to add text, but 
    it adds the text as part of the transaction. The command is enclosed 
    in braces, and it is set as the value of the ScriptBlock parameter of 
    Use-Transaction. The UseTransaction parameter (UseTx) is required. 
 
 use-transaction {$t.append(" PowerShell")} -usetx 
 
    To see the current content of the transacted string in $t, use the 
    ToString method of the TransactedString object. 
                  
 $t.tostring()       
 
    The output shows that only the non-transacted changes are effective. 
 
 Windows 
 
    To see the current content of the transacted string in $t from within 
    the transaction, embed the expression in a Use-Transaction command.   
 
 use-transaction {$s.tostring()} -usetx       
 
    The output shows the transaction view. 
 
 Windows PowerShell 
 
    The following command commits the transaction. 
 
 complete-transaction 
 
    To see the final string: 
 
 $t.tostring() 
 
 Windows PowerShell 
 
 

EXAMPLE 7: MANAGING MULTI-SUBSCRIBER TRANSACTIONS

 
    When you start a transaction while another transaction is in 
    progress, Windows PowerShell does not create a second transaction 
    by default. Instead, it adds a subscriber to the current  
    transaction.  
 
    This example shows how to view and manage a multi-subscriber  
    transaction. 
 
    Begin by starting a transaction in the HKCU:\Software key. 
 
        start-transaction 
     
    The following command uses the Get-Transaction command to  
    get the active transaction. 
 
get-transaction 
 
 
    The result shows the object that represents the active transaction. 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                1                 Active  
      
      
    The following command adds the MyCompany key to the registry. 
    The command  uses the UseTransaction parameter to include the 
    command in the transaction. 
                  
        new-item MyCompany -UseTransaction 
 
 
    The following command uses the Start-Transaction command to 
    start a transaction. Although this command is typed at the command 
    prompt, this scenario is more likely to happen when you run a 
    script that contains a transaction. 
 
        start-transaction 
 
 
    A Get-Transaction command shows that the subscriber count on the 
    transaction object is incremented. The value is now 2.      
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                2                 Active  
      
 
    The next command uses the New-ItemProperty cmdlet to add the  
    MyKey registry entry to the MyCompany key. It uses the UseTransaction 
    parameter to include the command in the transaction. 
 
        new-itemproperty -path MyCompany -name MyKey -UseTransaction 
 
 
    The MyCompany key does not exist in the registry, but this  
    command succeeds because the two commands are part of the  
    same transaction. 
 
    The following command commits the transaction. If it rolled back 
    the transaction, the transaction would be rolled back for all the 
    subscribers. 
 
complete-transaction 
 
 
    A Get-Transaction command shows that the subscriber count on the 
    transaction object is 1, but the value of Status is still Active 
    (not Committed).      
 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                1                 Active  
 
 
    To finish committing the transaction, enter a second Complete- 
    Transaction command. To commit a multi-subscriber transaction, 
    you must enter one Complete-Transaction command for each 
    Start-Transaction command. 
 
     complete-transaction 
 
       
    Another Get-Transaction command shows that the transaction 
    has been committed. 
 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                0                 Committed  
  
 

EXAMPLE 8: MANAGING INDEPENDENT TRANSACTIONS

 
    When you start a transaction while another transaction is in 
    progress, you can use the Independent parameter of Start-Transaction 
    to make the new transaction independent of the original transaction. 
 
    When you do, Start-Transaction creates a new transaction object 
    and makes the new transaction the active transaction. 
 
    Begin by starting a transaction in the HKCU:\Software key. 
 
        start-transaction 
      
    The following command uses the Get-Transaction command to  
    get the active transaction. 
 
get-transaction 
 
 
    The result shows the object that represents the active transaction. 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                1                 Active  
      
      
    The following command adds the MyCompany registry key as part of 
    the transaction. It uses the UseTransaction parameter (UseTx)  
    to include the command in the active transaction. 
 
new-item MyCompany -use 
 
 
    The following command starts a new transaction. The command uses 
    the Independent parameter to indicate that this transaction 
    is not a subscriber to the active transaction. 
 
         start-transaction -independent 
 
    When you create an independent transaction, the new (most-recently 
    created) transaction becomes the active transaction. You can use 
    a Get-Transaction command to get the active transaction.  
 
get-transaction 
 
    Note that the SubscriberCount of the transaction is 1, indicating 
    that there are no other subscribers and that the transaction is  
    new. 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                1                 Active  
 
    The new transaction must be finished (either committed or rolled 
    back) before you can manage the original transaction. 
 
    The following command adds the MyOtherCompany key to the registry. 
    It uses the UseTransaction parameter (UseTx) to include the command 
    in the active transaction. 
 
        new-item MyOtherCompany -usetx 
 
    Now, roll back the transaction. If there were a single 
    transaction with two subscribers, rolling back the transaction  
    would roll back the entire transaction for all the subscribers. 
 
    However, because these transactions are independent, rolling 
    back the newest transaction cancels the registry changes and  
    makes the original transaction the active transaction. 
 
        undo-transaction 
 
    A Get-Transaction command confirms that the original 
    transaction is still active in the session. 
 
 
get-transaction 
 
        RollbackPreference   SubscriberCount   Status 
        ------------------   ---------------   ------ 
        Error                1                 Active  
      
    The following command commits the active transaction. 
 
        complete-transaction 
 
 
    A Get-ChildItem command shows that the registry has been 
    changed. 
 
dir m* 
 
 
        Hive: HKEY_CURRENT_USER\Software 
 
        SKC  VC Name                           Property 
        ---  -- ----                           -------- 
        83   1 Microsoft                      {(default)} 
         0   0 MyCompany                      {} 
 
 

SEE ALSO

Start-Transaction
Get-Transaction
Complete-Transaction
Undo-Transaction
Use-Transaction
Registry (provider)
about_Providers
Get-PSProvider
Get-ChildItem