PowerShell Transactions QuickStart

PowerShell Team

The second CTP of PowerShell V2 (CTP2) introduces full engine support for transactions – groups of actions that can be finalized or undone in an all-or-nothing way. Wikipedia gives a great overview of transactions here: http://en.wikipedia.org/wiki/Database_transactions.

 

We put a ton of thought into how to expose this normally developer-centric concept in a way suitable for system administration and system administrators. We would LOVE to hear your feedback on what concepts or behaviours make sense, and especially which ones do not.

 

We didn’t get a chance to fully document these cmdlets in the CTP2, though, so here’s a quick start and primer to help you explore the feature.

 

Using transactions

PowerShell surfaces its support for transactions through the following cmdlets:

PS C:\Temp> gcm *transaction*

 

CommandType     Name

———–     —-

Cmdlet          Complete-PSTransaction

Completes / Commits a transaction

 

Cmdlet          Start-PSTransaction

Begins a transaction

 

Cmdlet          Undo-PSTransaction

Rolls back a transaction

 

Cmdlet          Use-PSTransaction

Places the current PowerShell transaction in Transaction.Current, for direct .NET Scripting against transacted objects.

 

To start a transaction, call the Start-PSTransaction cmdlet. To use a cmdlet that supports transactions, call it with the –UseTransaction parameter. Being explicit about this parameter is crucial, as many cmdlets that support transactions can work equally well without one. Because of that, PowerShell only surfaces the transaction to the cmdlet when you supply this parameter.

PowerShell’s registry provider supports transactions on Vista. In addition, a utility class called System.Management.Automation.TransactedString supports transactions on all platforms.

Once you have completed the transactional work, call the Complete-PSTransaction cmdlet to make it final, or the Undo-PSTransaction cmdlet to discard the changes.

 

Here is an example session that illustrates these concepts:

PS C:\Users\leeholm> cd hkcu:\temp

PS HKCU:\temp> dir

PS HKCU:\temp> Start-PsTransaction

 

## Create a key. We didn’t specify the –UseTransaction parameter, so it is not being done in a transaction.

PS HKCU:\temp> New-Item WillStayBehind

 

 

   Hive: Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\temp

 

SKC  VC Name                           Property

  — —-                           ——–

  0   0 WillStayBehind                 {}

 

 

## Create a key in the transaction

PS HKCU:\temp> New-Item WillGetRolledBack -UseTransaction

 

 

   Hive: Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\temp

 

SKC  VC Name                           Property

  — —-                           ——–

  0   0 WillGetRolledBack              {}

 

 

## Get-ChildItem from outside of the transaction. You don’t see any of your transacted changes.

PS HKCU:\temp> Get-ChildItem

 

 

   Hive: Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\temp

 

SKC  VC Name                           Property

  — —-                           ——–

  0   0 WillStayBehind                 {}

 

 

## Get-ChildItem from inside of the transaction. Your transacted changes are now visible.

PS HKCU:\temp> Get-ChildItem -UseTransaction

 

 

   Hive: Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\temp

 

SKC  VC Name                           Property

  — —-                           ——–

  0   0 WillStayBehind                 {}

  0   0 WillGetRolledBack              {}

 

 

## Now, some transacted .NET scripting against the TransactedString object

PS HKCU:\temp> $transactedString = New-Object System.Management.Automation.TransactedString

PS HKCU:\temp> $transactedString.Append(“Hello “)

 

## Append some text in the transaction.

PS HKCU:\temp> Use-PsTransaction -UseTransaction { $transactedString.Append(“World”) }

 

## From outside the transaction, the changes are not visible

PS HKCU:\temp> $transactedString.ToString()

Hello

 

## But from within the transaction, they are

PS HKCU:\temp> Use-PsTransaction -UseTransaction { $transactedString.ToString() }

Hello World

 

## Roll back the transaction

PS HKCU:\temp> Undo-PsTransaction

 

## Look at the registry, and only our non-transacted changes are there.

PS HKCU:\temp> Get-ChildItem

 

 

   Hive: Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\temp

 

SKC  VC Name                           Property

  — —-                           ——–

  0   0 WillStayBehind                 {}

 

 

PS HKCU:\temp> Get-ChildItem -UseTransaction

Get-ChildItem : Cannot use transaction. No transaction has been started.

At line:1 char:14

+ Get-ChildItem <<<<  -UseTransaction

PS HKCU:\temp> $transactedString.ToString()

Hello

PS HKCU:\temp>

 

Developing for transactions – Cmdlet and Provider declarations

Cmdlets declare their support for transactions in a similar way that they declare their support for ShouldProcess:

[Cmdlet(“Get”, “Process”, SupportsTransactions=True)]

 

Providers declare their support for transactions through the ProviderCapabilities flag:

[CmdletProvider(“Registry”, ProviderCapabilities.Transactions)]

 

Developing for transactions – Participating in the PowerShell transaction

The PowerShell engine exposes transactions in a way that lets developers implement a transacted provider or cmdlet in the same way that they implement other transacted code.

The recommended pattern for developing isolated transacted code in traditional applications is this: http://msdn2.microsoft.com/en-us/library/ms229973.aspx

using(TransactionScope scope = new TransactionScope())

{

   … // Perform transactional work here

 

   // No errors – commit transaction
   scope.Complete();

}

 

This is called implicit transaction management, and the code in the code block represents the entirety of the transacted operation. The TransactionScope object handles management of the ambient transaction, committing and rolling it back as necessary.

Since cmdlet and provider developers should not deal directly with transaction scopes (but still be able to easily port transacted code,) PowerShell gives a similar experience:

using(CurrentPsTransaction)
{
   ... // Perform transactional work here
}

 

The CurrentPsTransaction property returns an IDisposable object. This IDisposable object, through the System.Transactions explicit programming model (http://msdn2.microsoft.com/en-us/library/ms172146.aspx), sets the current ambient transaction to be the current PowerShell Transaction. Its dispose method restores the previous ambient transaction. Attempting to use this current transaction while no transactions are active generates an error. The other transaction cmdlets control the nesting and lifetime of these transactions.

This CurrentPsTransaction experience differs from the C# TransactionScope experience in two ways:

1)     The object returned by the CurrentPsTransaction property does not actually represent a transaction. It does not support a Complete() method, Rollback() method, or anything else. The user is in charge of these decisions, not the cmdlet or provider developer.

2)     The transaction persists beyond the end of the code block, as multiple cmdlets can participate in it. Although the transaction persists outside of the code block, it is not active / ambient outside of the code block. A cmdlet or provider author can easily write the following code to tightly control which operations are transacted:

using(CurrentPsTransaction)
{
   ... // Perform transactional work here
}
 
... // Perform non-transacted work here
 
using(CurrentPsTransaction)
{
   ... // Perform more transactional work here
}
 

 

Using the same pattern PowerShell has established for the ShouldProcess functionality, cmdlet and provider authors should check for an existing transaction if they can operate without one:

if(TransactionAvailable())
{
    using(CurrentPsTransaction)
    {
       ... // Perform transactional work here
    }
}

 

If the cmdlet or provider cannot operate without a transaction, they can simply use the CurrentPsTransaction property. If no transaction is available, PowerShell automatically generates an error.

 

Lee Holmes [MSFT]

Windows PowerShell Development

0 comments

Discussion is closed.

Feedback usabilla icon