スクリプト ブロックを有効なトランザクションに追加します。
構文
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」を参照してください。
パラメーター
-TransactedScript <scriptblock>
トランザクションで実行されるスクリプト ブロックを指定します。有効なスクリプト ブロックを中かっこ ( { } ) で囲んで入力します。このパラメーターは必須です。
|
必須 |
true |
|
位置 |
1 |
|
既定値 |
なし |
|
パイプライン入力を許可する |
false |
|
ワイルドカード文字を許可する |
false |
-UseTransaction
コマンドを有効なトランザクションに含めます。このパラメーターは、トランザクションの進行中のみ有効です。詳細については、「about_Transactions」を参照してください。
|
必須 |
false |
|
位置 |
named |
|
既定値 |
|
|
パイプライン入力を許可する |
false |
|
ワイルドカード文字を許可する |
false |
<CommonParameters>
このコマンドレットは、次の共通パラメーターをサポートします: -Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer、および -OutVariable。Ô”¼š¤Ë¤Ä¤¤¤Æ¤Ï¡¢次を参照してください: about_Commonparameters.
入力と出力
入力値の型は、コマンドレットへのパイプが可能なオブジェクトの型です。戻り値の型は、コマンドレットによって返されるオブジェクトの型です。
|
入力 |
なし パイプを使用してこのコマンドレットに入力を渡すことはできません。 |
|
出力 |
PSObject Use-Transaction コマンドレットは、トランザクションの結果を返します。 |
注
Use-Transaction パラメーターは、コマンドをアクティブなトランザクションに参加させるためのパラメーターです。Use-Transaction コマンドレットはトランザクションで常に使用されるので、Use-Transaction コマンドを有効にするには、このパラメーターは必須です。
例 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
説明
-----------
この例では、Use-Transaction コマンドレットを使用して、トランザクション対応の .NET Framework オブジェクトにスクリプトを実行する方法を示します。この例では、オブジェクトは TransactedString オブジェクトです。
最初のコマンドは、Start-Transaction コマンドレットを使用してトランザクションを開始します。
2 番目のコマンドは、New-Object コマンドを使用して TransactedString オブジェクトを作成します。オブジェクトは $TransactedString 変数に保存されます。
3 番目と 4 番目のコマンドはどちらも、TransactedString オブジェクトの Append メソッドを使用して、テキストを $TransactedString の値に追加します。一方のコマンドはトランザクションの一部であり、もう一方はトランザクションの一部ではありません。
3 番目のコマンドは、トランザクション文字列の Append メソッドを使用して、"Hello" を $TransactedString の値に追加します。このコマンドはトランザクションの一部ではないので、変更内容は直ちに反映されます。
4 番目のコマンドは、Use-Transaction コマンドレットを使用してテキストをトランザクション内の文字列に追加します。Append メソッドを使用して、", World" を $TransactedString の値に追加します。コマンドは中かっこ ({}) で囲んで、スクリプト ブロックにします。このコマンドでは UseTransaction パラメーターが必須です。
5 番目と 6 番目のコマンドは、TransactedString オブジェクトの ToString メソッドを使用して、TransactedString の値を文字列として表示します。ここでも、一方のコマンドはトランザクションの一部であり、もう一方はトランザクションの一部ではありません。
5 番目のコマンドは、ToString メソッドを使用して $TransactedString 変数の現在の値を表示します。このコマンドはトランザクションの一部ではないので、文字列の現在の状態のみを表示します。
6 番目のコマンドは、Use-Transaction コマンドレットを使用してトランザクション内で同じコマンドを実行します。このコマンドはトランザクションの一部なので、トランザクション内の文字列の現在の値を表示します。これは、トランザクションの変更内容をプレビューするようなものです。
7 番目のコマンドは、Complete-Transaction コマンドレットを使用してトランザクションをコミットします。
最後のコマンドは、ToString メソッドを使用して、結果として得られる変数の値を文字列として表示します。
例 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
説明
-----------
この例では、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 の値を文字列として表示します。トランザクションの外部で行われた変更だけがオブジェクトに反映されたことが結果に示されます。
関連項目