Use-Transaction
スクリプト ブロックを有効なトランザクションに追加します。
構文
Use-Transaction
[-TransactedScript] <ScriptBlock>
[-UseTransaction]
[<CommonParameters>]説明
Use-Transaction コマンドレットは、アクティブなトランザクションにスクリプト ブロックを追加します。 これにより、トランザクション対応の Microsoft .NET Framework オブジェクトを使用して、トランザクション スクリプトを実行できます。 スクリプト ブロックに格納できるのは、Microsoft.PowerShell.Commands.Management.TransactedString クラスのインスタンスなど、トランザクション対応の .NET Framework オブジェクトだけです。
このコマンドレットを使用する場合は、 UseTransaction パラメーター (ほとんどのコマンドレットでは省略可能) が必要です。
Use-Transaction は、Windows PowerShellのトランザクション機能をサポートするコマンドレットのセットの 1 つです。 詳細については、「about_Transactions」を参照してください。
例
例 1: トランザクションが有効なオブジェクトを使用してスクリプトを作成する
PS C:\> Start-Transaction
PS C:\> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
PS C:\> $transactedString.Append("Hello")
PS C:\> Use-Transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
PS C:\> $transactedString.ToString()
Hello
PS C:\> Use-Transaction -TransactedScript { $transactedString.ToString() } -UseTransaction
Hello, World
PS C:\> Complete-Transaction
PS C:\> $transactedString.ToString()
Hello, Worldこの例では、Use-Transaction を使用して、トランザクションが有効な.NET Framework オブジェクトに対してスクリプトを作成する方法を示します。 この場合、オブジェクトは TransactedString オブジェクトです。
最初のコマンドは、Start-Transaction コマンドレットを使用してトランザクションを開始します。
2 番目のコマンドでは、New-Object コマンドを使用して TransactedString オブジェクトを作成します。 オブジェクトは $TransactedString 変数に保存されます。
3 番目と 4 番目のコマンドはどちらも TransactedString オブジェクトの Append メソッドを使用して、$TransactedStringの値にテキストを追加します。 1 つのコマンドがトランザクションの一部です。 もう 1 つのコマンドはではありません。
3 番目のコマンドでは、トランザクション文字列の Append メソッドを使用して、$TransactedStringの値にHelloを追加します。 このコマンドはトランザクションの一部ではないので、変更内容は直ちに反映されます。
4 番目のコマンドでは 、Use-Transaction を使用して、トランザクション内の文字列にテキストを追加します。 コマンドは Append メソッドを使用して、", World" を $TransactedString の値に追加します。 コマンドは中かっこ ( {} ) で囲んでスクリプト ブロックにします。 このコマンドでは 、UseTransaction パラメーターが必要です。
5 番目と 6 番目のコマンドでは、TransactedString オブジェクトの ToString メソッドを使用して、TransactedString の値を文字列として表示します。 ここでも、1 つのコマンドがトランザクションの一部です。 もう 1 つのトランザクションはではありません。
5 番目のコマンドでは、 ToString メソッドを使用して、$TransactedString変数の現在の値を表示します。 このコマンドはトランザクションの一部ではないので、文字列の現在の状態のみを表示します。
6 番目のコマンドでは 、Use-Transaction を使用して、トランザクションで同じコマンドを実行します。 コマンドはトランザクションの一部であるため、トランザクションの変更のプレビューと同様に、トランザクション内の文字列の現在の値が表示されます。
7 番目のコマンドは、Complete-Transaction コマンドレットを使用してトランザクションをコミットします。
最後のコマンドでは 、ToString メソッドを使用して、変数の結果の値を文字列として表示します。
例 2: トランザクションをロールバックする
PS C:\> Start-Transaction
PS C:\> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
PS C:\> $transactedString.Append("Hello")
PS C:\> Use-Transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
PS C:\> Undo-Transaction
PS C:\> $transactedString.ToString()
Helloこの例では、 Use-Transaction コマンドを含むトランザクションをロールバックする効果を示します。 トランザクション内のすべてのコマンドと同様に、トランザクションをロールバックすると、トランザクションされた変更内容は破棄され、データは変更されません。
最初のコマンドでは 、Start-Transaction を使用してトランザクションを開始します。
2 番目のコマンドでは 、New-Object を 使用して TransactedString オブジェクトを作成します。 オブジェクトは $TransactedString 変数に保存されます。
トランザクションの一部ではない 3 番目のコマンドでは、Append メソッドを使用して、"Hello" を $TransactedString の値に追加します。
4 番目のコマンドでは 、Use-Transaction を 使用して、トランザクションで Append メソッドを使用する別のコマンドを実行します。 コマンドは Append メソッドを使用して、", World" を $TransactedString の値に追加します。
5 番目のコマンドは、Undo-Transaction コマンドレットを使用してトランザクションをロールバックします。 その結果、トランザクションで実行されたすべてのコマンドが元に戻されます。
最後のコマンドでは、 ToString メソッドを使用して、$TransactedStringの結果の値を文字列として表示します。 結果は、トランザクションの外部で行われた変更のみが オブジェクトに適用されたことを示しています。
パラメーター
-TransactedScript
トランザクションで実行されるスクリプト ブロックを指定します。 有効なスクリプト ブロックを中かっこ ( { } ) で囲んで入力します。 このパラメーターは必須です。
| Type: | ScriptBlock |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseTransaction
アクティブなトランザクションのコマンドが含まれます。 このパラメーターは、トランザクションが進行中の場合のみ有効です。 詳細については、「about_Transactions」を参照してください。
| Type: | SwitchParameter |
| Aliases: | usetx |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
入力
None
パイプを使用してこのコマンドレットに入力を渡すことはできません。
出力
PSObject
このコマンドレットは、トランザクションの結果を返します。
メモ
UseTransaction パラメーターには、アクティブなトランザクションに コマンドが含まれています。 Use-Transaction コマンドレットは常にトランザクションで使用されるため、Use-Transaction コマンドを有効にするには、このパラメーターが必要です。