Use-Transaction
アクティブなトランザクションにスクリプト ブロックを追加します。
構文
Default (既定)
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: トランザクションが有効なオブジェクトを使用したスクリプト
Start-Transaction
$transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
$transactedString.Append("Hello")
Use-Transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
$transactedString.ToString()
Hello
Use-Transaction -TransactedScript { $transactedString.ToString() } -UseTransaction
Hello, World
Complete-Transaction
$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 メソッドを使用して、hello を $TransactedStringの値に追加します。 コマンドはトランザクションの一部ではないため、変更はすぐに適用されます。
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: トランザクションをロールバックする
Start-Transaction
$transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
$transactedString.Append("Hello")
Use-Transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
Undo-Transaction
$transactedString.ToString()
Hello
この例では、Use-Transaction コマンドを含むトランザクションをロールバックする効果を示します。 トランザクション内のすべてのコマンドと同様に、トランザクションがロールバックされると、トランザクションの変更は破棄され、データは変更されません。
最初のコマンドでは、Start-Transaction を使用してトランザクションを開始します。
2 番目のコマンドでは、New-Object を使用して、TransactedString オブジェクトを作成します。
$TransactedString 変数にオブジェクトが格納されます。
トランザクションの一部ではない 3 番目のコマンドでは、Append メソッドを使用して、$TransactedStringの値に "Hello" を追加します。
4 番目のコマンドでは、Use-Transaction を使用して、トランザクションで Append メソッドを使用する別のコマンドを実行します。 このコマンドでは、Append メソッドを使用して、", World" を $TransactedStringの値に追加します。
5 番目のコマンドでは、Undo-Transaction コマンドレットを使用してトランザクションをロールバックします。 その結果、トランザクションで実行されたすべてのコマンドが元に戻されます。
最後のコマンドでは、ToString メソッドを使用して、$TransactedString の結果の値を文字列として表示します。 結果は、トランザクションの外部で行われた変更のみがオブジェクトに適用されたことを示しています。
パラメーター
-TransactedScript
トランザクションで実行されるスクリプト ブロックを指定します。 有効なスクリプト ブロックを中かっこ ({}) で囲み入力します。 このパラメーターは必須です。
パラメーターのプロパティ
| 型: | ScriptBlock |
| 規定値: | None |
| ワイルドカードのサポート: | False |
| DontShow: | False |
パラメーター セット
(All)
| 配置: | 0 |
| 必須: | True |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
-UseTransaction
アクティブなトランザクションにコマンドを含みます。 このパラメーターは、トランザクションが進行中の場合にのみ有効です。 詳細については、about_Transactionsを参照してください。
パラメーターのプロパティ
| 型: | SwitchParameter |
| 規定値: | False |
| ワイルドカードのサポート: | False |
| DontShow: | False |
| Aliases: | usetx |
パラメーター セット
(All)
| 配置: | Named |
| 必須: | False |
| パイプラインからの値: | False |
| プロパティ名別のパイプラインからの値: | False |
| 残りの引数からの値: | False |
CommonParameters
このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。
入力
None
このコマンドレットに入力をパイプすることはできません。
出力
PSObject
このコマンドレットは、トランザクションの結果を返します。
メモ
-
UseTransaction パラメーターには、アクティブなトランザクションにコマンドが含まれています。
Use-Transactionコマンドレットは常にトランザクションで使用されるため、Use-Transactionコマンドを有効にするには、このパラメーターが必要です。
