Category Archives: Transaction

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, 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, Start, Transaction

Start-Transaction

February 26, 2014 Adam

NAME
Start-Transaction

SYNOPSIS
Starts a transaction.

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

DESCRIPTION
The Start-Transaction cmdlet 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 commands are committed or all commands are rolled back.

By default, transactions are rolled back automatically if any command in the transaction generates an error, but you can use the RollbackPreference parameter 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 Windows PowerShell Registry provider in Windows Vista and later versions of Windows supports transactions. You can also use the Microsoft.PowerShell.Commands.Management.TransactedString class to include expressions in transactions on any version of Windows that supports Windows PowerShell. Other Windows PowerShell providers can also support transactions.

Only one transaction can be active at a time. If you start a new, independent transaction while a transaction is in progress (neither completed nor undone), the new transaction becomes the active transaction, and you must commit or roll back the new transaction before making any changes to the original transaction.

The Start-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_transactions.

PARAMETERS
-Independent [<SwitchParameter>]
Starts 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 has an effect only 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 rolls back the entire the transaction. To complete the transaction, you must enter a Complete-Transaction command 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, you must complete or roll back the new transaction before resuming work on the original transaction.

        Required?                    false
        Position?                    named
        Default value                Reuse the original transaction object.
        Accept pipeline input?     false
        Accept wildcard characters? false

-RollbackPreference <RollbackSeverity>
Specifies the conditions under which a transaction is automatically rolled back. The default value is “Error”.

Valid values are:

        — Error: The transaction is rolled back automatically if a terminating or non-terminating error occurs. “Error” is the default.
        — Terminating error: The transaction is rolled back automatically if a terminating error occurs.
        — Never: The transaction is never rolled back automatically.

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

-Timeout <int>
Specifies the maximum time, in minutes, that the transaction is 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.

        Required?                    false
        Position?                    named
        Default value                No timeout (infinite)
        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
None
You cannot pipe input to this cmdlet.

OUTPUTS
None
This cmdlet does not generate any output.

NOTES

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

C:\PS>cd hkcu:\software

PS HKCU:\software> Start-Transaction

PS HKCU:\software> New-Item MyCompany -UseTransaction

PS HKCU:\software> New-Itemproperty MyCompany -name MyKey -value 123 -UseTransaction

PS HKCU:\software> Undo-Transaction

    Description
    ———–
    These commands start and then roll back a transaction. Because the transaction is rolled back, no changes are made to the Registry.

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

C:\PS>cd hkcu:\software

PS HKCU:\software> Start-Transaction

PS HKCU:\software> New-Item MyCompany -UseTransaction

PS HKCU:\software> New-Itemproperty MyCompany -name MyKey -value 123 -UseTransaction

PS HKCU:\software> Complete-Transaction

    Description
    ———–
    These commands start and then complete a transaction. No changes are made to the Registry until the Complete-Transaction command is used.

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

    C:\PS>cd HKCU:\software
    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item -path NoPath -name MyCompany -UseTransaction
    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction

    PS HKCU:\software> Start-Transaction -RollbackPreference never
    PS HKCU:\software> New-Item -path NoPath -name MyCompany -UseTransaction
    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction

# Start-Transaction (-RollbackPreference error)

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item -path NoPath -Name MyCompany -UseTransaction
    New-Item : The Registry key at the specified path does not exist.
    At line:1 char:9
    + New-Item <<<< -path NoPath -Name MyCompany -UseTransaction

    PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction
    New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
    At line:1 char:9
    + New-Item <<<< -path . -name MyCompany -UseTransaction

    # Start-Transaction (-RollbackPreference never)
    PS HKCU:\software> Start-Transaction -RollbackPreference never
    PS HKCU:\software> New-Item -path NoPath -name MyCompany -UseTransaction
    New-Item : The Registry key at the specified path does not exist.
    At line:1 char:9
    + New-Item <<<< -path NoPath -name MyCompany -UseTransaction

PS HKCU:\software> New-Item -path . -name MyCompany -UseTransaction
Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany                     {}

PS HKCU:\Software> Complete-Transaction
# Succeeds

    Description
    ———–
    This example demonstrates the effect of changing the RollbackPreference parameter value.

In the first set of commands, the Start-Transaction command does not use the RollbackPreference parameter. As a result, the default value (“Error”) is used. When an error occurs in a transaction command (the specified path does not exist), the transaction is automatically rolled back.

In the second set of commands, the Start-Transaction command uses the RollbackPreference parameter with a value of “Never”. As a result, when an error occurs in a transaction command, the transaction is still active and can be completed successfully.

Because most transactions must be performed without error, the default value of the RollbackPreference parameter is typically preferred.

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

C:\PS>cd HKCU:\software

PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> Get-Transaction
    PS HKCU:\software> New-Item MyCompany2 -UseTransaction

PS HKCU:\software> Complete-Transaction
PS HKCU:\software> Complete-Transaction

PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                2                 Active

    Description
    ———–
    This example shows the effect of using the Start-Transaction command while a transaction is in progress. The effect is much like joining the transaction in progress.

Although this is a simplified command, this scenario commonly occurs when the transaction involves running a script that includes a complete transaction.

The first Start-Transaction command starts the transaction. The first New-Item command is part of the transaction.

The second Start-Transaction command adds a new subscriber to the transaction. The Get-Transaction command now returns a transaction with a subscriber count of 2. The second New-Item command is part of the same transaction.

No changes are made to the Registry until the entire transaction is completed. To complete the transaction, you must enter two Complete-Transaction commands, one for each subscriber. If you were to roll back the transaction at any point, the entire transaction would be rolled back for both subscribers.

————————– EXAMPLE 5 ————————–

    C:\PS>cd HKCU:\software
    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> Start-Transaction -Independent
    PS HKCU:\software> Get-Transaction
    PS HKCU:\software> Undo-Transaction

    PS HKCU:\software> New-Itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> dir my*

PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                1                 Active

PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-Itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction

    MyKey
    —–
    123

PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir my*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 1 MyCompany                     {MyKey}

    Description
    ———–
    This example shows the effect of using the Independent parameter of Start-Transaction to start a transaction while another transaction is in progress. In this case, the new transaction is rolled back without affecting the original transaction.

Although the transactions are logically independent, because only one transaction can be active at a time, you must roll back or commit the newest transaction before resuming work on the original transaction.

The first set of commands starts a transaction. The New-Item command is part of the first transaction.

In the second set of commands, the Start-Transaction command uses the Independent parameter. The Get-Transaction command that follows shows the transaction object for the active transaction (the newest one). The subscriber count is equal to 1, showing that the transactions are unrelated.

When the active transaction is rolled back by using an Undo-Transaction command, the original transaction becomes active again.

The New-ItemProperty command, which is part of the original transaction, completes without error, and the original transaction can be completed by using the Complete-Transaction command. As a result, the Registry is changed.

————————– EXAMPLE 6 ————————–

C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item MyCompany1 -UseTransaction
    PS HKCU:\software> New-Item MyCompany2
    PS HKCU:\software> New-Item MyCompany3 -UseTransaction

PS HKCU:\software> dir my*

PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir my*

PS HKCU:\Software> dir my*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany2                     {}

PS HKCU:\Software> Complete-Transaction

PS HKCU:\Software> dir my*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany1                     {}
     0 0 MyCompany2                     {}
     0 0 MyCompany3                     {}

    Description
    ———–
    This example demonstrates that commands that are submitted while a transaction is in progress can be included in the transaction or not included. Only commands that use the UseTransaction parameter are part of the transaction.

The first and third New-Item commands use the UseTransaction parameter. These commands are part of the transaction. Because the second New-Item command does not use the UseTransaction parameter, it is not part of the transaction.

The first “dir” command shows the effect. The second New-Item command is completed immediately, but the first and third New-Item commands are not effective until the transaction is committed.

The Complete-Transaction command commits the transaction. As a result, the second “dir” command shows that all of the new items are added to the Registry.

————————– EXAMPLE 7 ————————–

C:\PS>Start-Transaction -Timeout 2

# Wait two minutes…

C:\PS> Get-Transaction

C:\PS> New-Item HKCU:\Software\MyCompany -UseTransaction

C:\PS> Start-Transaction -Timeout 2

# Wait two minutes…

C:\PS>> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ———–
    Error                1                 RolledBack

    C:\PS> New-Item HKCU:\Software\MyCompany -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

    Description
    ———–
    This command uses 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 is rolled back automatically.

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.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135262
    about_transactions
    Get-Transaction
    Complete-Transaction
    Undo-Transaction
    Use-Transaction

cmdlet, Get, Transaction

Get-Transaction

February 26, 2014 Adam

NAME
Get-Transaction

SYNOPSIS
Gets the current (active) transaction.

SYNTAX
Get-Transaction [<CommonParameters>]

DESCRIPTION
The Get-Transaction cmdlet gets an object that represents the current transaction in the session.

This cmdlet never returns more than one object, because only one transaction is active at a time. If you start one or more independent transactions (by using the Independent parameter of Start-Transaction), the most recently started transaction is active, and that is the transaction that Get-Transaction returns.

When all active transactions have either been rolled back or committed, Get-Transaction shows the transaction that was most recently active in the session.

The Get-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_transactions.

PARAMETERS
    <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 objects to this cmdlet.

OUTPUTS
System.Management.Automation.PSTransaction
Get-Transaction returns an object that represents the current transaction.

NOTES

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

C:\PS>Start-Transaction

C:\PS> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                1                 Active

    Description
    ———–
    This command uses the Get-Transaction cmdlet to get the current transaction.

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

C:\PS>Get-Transaction | Get-Member

    Name             MemberType Definition
    —-             ———- ———-
    Dispose            Method     System.Void Dispose(), System.Void Dispose(Boolean disposing)
    Equals             Method     System.Boolean Equals(Object obj)
    GetHashCode        Method     System.Int32 GetHashCode()
    GetType            Method     System.Type GetType()
    ToString         Method     System.String ToString()
    IsCommitted        Property System.Boolean IsCommitted {get;}
    IsRolledBack     Property System.Boolean IsRolledBack {get;}
    RollbackPreference Property System.Management.Automation.RollbackSeverity RollbackPreference {get;}
    SubscriberCount    Property System.Int32 SubscriberCount {get;set;}

    Description
    ———–
    This command uses the Get-Member cmdlet to show the properties and methods of the transaction object.

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

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

    RollbackPreference SubscriberCount Status
    —————— ————— ———-
    Error                0                 RolledBack

    Description
    ———–
    This command shows the property values of a transaction object for a transaction that has been rolled back.

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

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

    RollbackPreference SubscriberCount Status
    —————— ————— ———
    Error                1                 Committed

    Description
    ———–
    This command shows the property values of a transaction object for a transaction that has been committed.

————————– EXAMPLE 5 ————————–

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

HKLM:\SOFTWARE> Start-Transaction
HKLM:\SOFTWARE> New-Item MyCompany2 -UseTransaction

HKLM:\SOFTWARE> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                2                 Active

HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                1                 Active

HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ———
    Error                1                 Committed

    Description
    ———–
    This example shows the effect on the transaction object of starting a transaction while another transaction is in progress. Typically, this happens when a script that runs a transaction includes a Function or calls a script that contains another complete transaction.

Unless the second Start-Transaction command includes the Independent parameter, Start-Transaction does not create a new transaction. Instead, it adds a second subscriber to the original transaction.

The first Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter is part of the transaction.

A second Start-Transaction command adds a subscriber to the transaction. The next New-Item command is also part of the transaction.

The first Get-Transaction command shows the multi-subscriber transaction. Notice that the subscriber count is 2.

The first Complete-Transaction command does not commit the transaction, but it reduces the subscriber count to 1.

The second Complete-Transaction command commits the transaction.

————————– EXAMPLE 6 ————————–

C:\PS>HKLM:\SOFTWARE> Start-Transaction

HKLM:\SOFTWARE> Get-Transaction

    RollbackPreference SubscriberCount IsRolledBack IsCommitted
    —————— ————— ———— ———–
    Error                1                 False         False

HKLM:\SOFTWARE> Start-Transaction -Independent
HKLM:\SOFTWARE> Get-Transaction

    RollbackPreference SubscriberCount IsRolledBack IsCommitted
    —————— ————— ———— ———–
    Error                1                 False         False

HKLM:\SOFTWARE> Complete-Transaction
HKLM:\SOFTWARE> Get-Transaction

    Description
    ———–
    This example shows the effect on the transaction object of starting an independent transaction while another transaction is in progress.

The first Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter is part of the transaction.

A second Start-Transaction command adds a subscriber to the transaction. The next New-Item command is also part of the transaction.

The first Get-Transaction command shows the multi-subscriber transaction. Note that the subscriber count is 2.

The Complete-Transaction command reduces the subscriber count to 1, but it does not commit the transaction.

The second Complete-Transaction command commits the transaction.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135220
    about_transactions
    about_providers
    Start-Transaction
    Complete-Transaction
    Undo-Transaction
    Use-Transaction

cmdlet, Complete, Transaction

Complete-Transaction

February 26, 2014 Adam

NAME
Complete-Transaction

SYNOPSIS
Commits the active transaction.

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

DESCRIPTION
The Complete-Transaction cmdlet commits an active transaction. When you commit a transaction, the commands in the transaction are finalized and the data affected by the commands is changed.

If the transaction includes multiple subscribers, to commit the transaction, you must enter one Complete-Transaction command for every Start-Transaction command.

The Complete-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 objects to Complete-Transaction.

OUTPUTS
None
This cmdlet does not return any objects.

NOTES

You cannot roll back a transaction that has been committed, or commit a transaction that has been rolled back.

You cannot roll back any transaction other than the active transaction. To roll back a different transaction, you must first commit or roll back the active transaction.

By default, if any part of a transaction cannot be committed, such as when a command in the transaction results in an error, the entire transaction is rolled back.

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

C:\PS>cd hkcu:\software

PS HKCU:\software> Start-Transaction

PS HKCU:\software> New-Item MyCompany -UseTransaction
PS HKCU:\software> dir m*

Hive: HKEY_CURRENT_USER\software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}

PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir m*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}
     0 0 MyCompany                     {}

    Description
    ———–
    This example shows the effect of using the Complete-Transaction cmdlet to commit a transaction.

The Start-Transaction command starts the transaction. The New-Item command uses the UseTransaction parameter to include the command in the transaction.

The first “dir” (Get-ChildItem) command shows that the new item has not yet been added to the Registry.

The Complete-Transaction command commits the transaction, which makes the Registry change effective. As a result, the second “dir” command shows that the Registry is changed.

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

C:\PS>cd hkcu:\software

PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item MyCompany -UseTransaction

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany                     {}

PS HKCU:\software> Start-Transaction
PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                2                Active

PS HKCU:\software> New-Itemproperty -path MyCompany -name MyKey -value -UseTransaction

    MyKey
    —–
    123

PS HKCU:\software> Complete-Transaction
PS HKCU:\software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                1                Active

PS HKCU:\software> dir m*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}

PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir m*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}
     0 1 MyCompany                     {MyKey}

    Description
    ———–
    This example shows how to use Complete-Transaction to commit a transaction that has more than one subscriber.

To commit a multi-subscriber transaction, you must enter one Complete-Transaction command for every Start-Transaction command. The data is changed only when the final Complete-Transaction command is submitted.

For demonstration purposes, this example shows a series of commands entered at the command line. In practice, transactions are likely to be run in scripts, with the secondary transaction being run by a Function or helper script that is called by the main script.

In this example, a Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter adds the MyCompany key to the Software key. Although the New-Item command returns a key object, the data in the Registry is not yet changed.

A second Start-Transaction command adds a second subscriber to the existing transaction. The Get-Transaction command confirms that the subscriber count is 2. A New-ItemProperty command with the UseTransaction parameter adds a Registry entry to the new MyCompany key. Again, the command returns a value, but the Registry is not changed.

The first Complete-Transaction command reduces the subscriber count by 1. This is confirmed by a Get-Transaction command. However, no data is changed, as evidenced by a “dir m*” (Get-ChildItem) command.

The second Complete-Transaction command commits the entire transaction and changes the data in the Registry. This is confirmed by a second “dir m*” command, which shows the changes.

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

C:\PS>cd hkcu:\software

PS HKCU:\software> Start-Transaction

PS HKCU:\software> New-Item MyCompany -UseTransaction

PS HKCU:\software> dir m*

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}

PS HKCU:\software> dir m* -UseTransaction

Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}
     0 0 MyCompany                     {}

PS HKCU:\software> Complete-Transaction

    Description
    ———–
    This example shows the value of using Get-* commands, and other commands that do not change data, in a transaction. When a Get-* command is used in a transaction, it gets the objects that are part of the transaction. This allows you to preview the changes in the transaction before the changes are committed.

In this example, a transaction is started. A New-Item command with the UseTransaction parameter adds a new key to the Registry as part of the transaction.

Because the new Registry key is not added to the Registry until the Complete-Transaction command is run, a simple “dir” (Get-ChildItem) command shows the Registry without the new key.

However, when you add the UseTransaction parameter to the “dir” command, the command becomes part of the transaction, and it gets the items in the transaction even if they are not yet added to the data.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135200
    about_transactions
    Start-Transaction
    Get-Transaction
    Undo-Transaction
    Use-Transaction