Start-Transaction

Start a transaction.

Syntax
      Start-Transaction [-Independent]
         [-RollbackPreference {Error | TerminatingError | Never}]
            [-Timeout int] [-Confirm] [-WhatIf]  [CommonParameters]

Key
   -Independent
       Start a transaction that is independent of any transactions in progress.
       By default, if you use Start-Transaction while another transaction is in
       progress, a new subscriber is added to the transaction in progress.
       This parameter only takes effect when a transaction is already in progress in the session. 
        
       By default, if you use Start-Transaction while a transaction is in progress,
       the existing transaction object is reused and the subscriber count is
       incremented. The effect is much like joining the original transaction.
       An Undo-Transaction command will roll back the entire the transaction.
       To complete the transaction, a Complete-Transaction command must be run for
       each subscriber. Because most transactions that are in progress at the same time
       are related, the default is sufficient for most uses.
        
       If you use the -Independent parameter, a new transaction is created that
       can be completed or undone without affecting the original transaction.
       However, because only one transaction can be active at a time, the new
       transaction must be completed or rolled back before resuming the original transaction.
        
   -RollbackPreference RollbackSeverity
       The conditions under which a transaction is automatically rolled back.
       Valid values:
        
         Error              The transaction is rolled back automatically if a 
                            terminating or non-terminating error occurs.
         Terminating error  The transaction is rolled back automatically if a
                            terminating error occurs.
         Never              The transaction is never rolled back automatically.
        
   -Timeout int
       The maximum time, in minutes, that the transaction may be active.
       When the time-out expires, the transaction is automatically rolled back. 
        
       By default, there is no time-out for transactions that are started at
       the command line. When transactions are started by a script, the
       default time-out is 30 minutes.

   -Confirm
       Prompt for confirmation before executing the command.

   -WhatIf
       Describe what would happen if the command was executed without actually
       executing the command.

   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer -OutVariable.

Start-Transaction starts a transaction, which is a series of commands that are managed as a unit. A transaction can be completed ("committed"), or it can be completely undone ("rolled back") so that any data changed by the transaction is restored to its original state. Because the commands in a transaction are managed as a unit, either all the commands are committed or all are rolled back.

By default, transactions are rolled back automatically if any command in the transaction generates an error, the -RollbackPreference parameter may be used to change this behavior.

The cmdlets used in a transaction must be designed to support transactions. Cmdlets that support transactions have a -UseTransaction parameter.
To perform transactions in a provider, the provider must support transactions. The PowerShell Registry provider in Windows Vista and later versions of Windows supports transactions.

Examples

Show the properties and methods of the transaction object:

PS C:\> get-transaction | get-member

Show the property values of a transaction object for a transaction that has been committed:

PS C:\> cd hklm:\software
HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> New-Item SS64 -UseTransaction
HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction

Use the -Timeout parameter of Start-Transaction to start a transaction that must be completed within two minutes. If the transaction is not complete when the timeout expires, it will roll back automatically:

 PS C:\> start-transaction -timeout 2
 # Wait two minutes...
 PS C:\> get-transaction
 PS C:\> new-item HKCU:\Software\SS64 -UseTransaction
 PS C:\> start-transaction -timeout 2
 # Wait two minutes...
 PS C:\>> get-transaction

 RollbackPreference SubscriberCount Status
 ------------------ --------------- -----------
 Error              1               RolledBack 
 
 PS C:\> New-item HKCU:\Software\SS64 -UseTransaction
 New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
 At line:1 char:9
 + new-item <<<< MyCompany -UseTransaction

When the timeout expires, you are not notified, but the Status property of the transaction object is set to RolledBack and commands that use the UseTransaction parameter fail.

“For every sale you miss because you're too enthusiastic, you will miss a hundred because you're not enthusiastic enough” ~ Zig Ziglar

Related:

Complete-Transaction - Commit the transaction
Use-Transaction - Add a command or expression to the transaction
Undo-Transaction - Roll back a transaction


© Copyright SS64.com 1999-2013
Some rights reserved