Start-Transaction

Start-Transaction コマンドレットは、1 つの単位として管理される一連のコマンドであるトランザクションを開始します。 トランザクションは完了することも、コミットすることもできます。 または、トランザクションによって変更されたデータが元の状態に復元されるように、完全に元に戻すかロールバックすることもできます。 トランザクション内のコマンドは 1 つの単位として管理されるため、すべてのコマンドがコミットされるか、すべてのコマンドがロールバックされます。

既定では、トランザクション内のコマンドでエラーが生成された場合、トランザクションは自動的にロールバックされます。 この動作を変更するには、RollbackPreference パラメーターを使用できます。

トランザクションで使用されるコマンドレットは、トランザクションをサポートするように設計されている必要があります。 トランザクションをサポートするコマンドレットには、UseTransaction パラメーターがあります。 プロバイダーでトランザクションを実行するには、プロバイダーがトランザクションをサポートする必要があります。 Windows Vista 以降のバージョンの Windows オペレーティング システムの Windows PowerShell レジストリ プロバイダーは、トランザクションをサポートしています。 Microsoft.PowerShell.Commands.Management.TransactedString クラスを使用して、Windows PowerShell をサポートする任意のバージョンの Windows システム上のトランザクションに式を含めることもできます。 他の Windows PowerShell プロバイダーもトランザクションをサポートできます。

一度にアクティブにできるトランザクションは 1 つだけです。 トランザクションの進行中に新しい独立したトランザクションを開始すると、新しいトランザクションがアクティブなトランザクションになります。元のトランザクションに変更を加える前に、新しいトランザクションをコミットまたはロールバックする必要があります。

Start-Transaction コマンドレットは、Windows PowerShell のトランザクション機能をサポートする一連のコマンドレットの 1 つです。 詳細については、「about_Transactions」を参照してください。

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Undo-Transaction

これらのコマンドは、トランザクションを開始してからロールバックします。 トランザクションはロールバックされるため、レジストリに変更は加えわれません。

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Complete-Transaction

これらのコマンドは、トランザクションを開始してから完了します。 Complete-Transaction コマンドが使用されるまで、レジストリは変更されません。

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction -RollbackPreference never
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction

# Start-Transaction (-rollbackpreference error)

PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<<  -Path NoPath -Name ContosoCompany -UseTransaction

PS HKCU:\software> New-Item -Path . -Name "Contoso" -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 ContosoCompany -UseTransaction

# Start-Transaction (-rollbackpreference never)

PS HKCU:\software> Start-Transaction -RollbackPreference never
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction

New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<<  -Path NoPath -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany                 {}
PS HKCU:\Software> Complete-Transaction

# Succeeds

この例では、RollbackPreference パラメーター値を変更した場合の影響を示します。

最初のコマンド セットでは、 Start-Transaction は RollbackPreference を使用しません。 その結果、既定値 (Error) が使用されます。 トランザクション コマンドでエラーが発生した場合、つまり、指定したパスが存在しない場合、トランザクションは自動的にロールバックされます。

2 番目のコマンド セットでは、 Start-Transaction は RollbackPreference を値 Never で使用します。 その結果、トランザクション コマンドでエラーが発生しても、トランザクションは引き続きアクティブであり、正常に完了できます。

ほとんどのトランザクションはエラーなしで実行する必要があるため、通常、RollbackPreference の既定値 使用することをお勧めします。

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction
PS HKCU:\software> Get-Transaction
PS HKCU:\software> New-Item "ContosoCompany2" -UseTransaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\Software> Get-Transaction
RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                2                 Active

この例では、トランザクションの進行中に Start-Transaction を使用した場合の影響を示します。 効果は、進行中のトランザクションに参加するのとよく似ています。

これは簡略化されたコマンドですが、このシナリオは、トランザクションが完全なトランザクションを含むスクリプトの実行を伴う場合に頻繁に発生します。

最初の Start-Transaction コマンドでトランザクションが開始されます。 最初の New-Item コマンドは、トランザクションの一部です。

2 番目の Start-Transaction コマンドは、トランザクションに新しいサブスクライバーを追加します。 Get-Transaction コマンドは、サブスクライバー数が 2 のトランザクションを返すようになりました。 2 番目の New-Item コマンドは、同じトランザクションの一部です。

トランザクション全体が完了するまで、レジストリに対する変更は行われません。 トランザクションを完了するには、サブスクライバごとに 1 つずつ、合計 2 つの Complete-Transaction コマンドを入力する必要があります。 任意の時点でトランザクションをロールバックすると、両方のサブスクライバーのすべてのトランザクションがロールバックされます。

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction -Independent
PS HKCU:\software> Get-Transaction
PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
PS HKCU:\Software> Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                1                 Active
PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
MyKey
-----
123
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   1 MyCompany                      {MyKey}

この例では、Start-Transaction の Independent パラメーターを使用して、別のトランザクションの進行中にトランザクションを開始する効果を示しています。 この場合、新しいトランザクションは元のトランザクションに影響を与えずにロールバックされます。

トランザクションは論理的に独立していますが、一度にアクティブにできるトランザクションは 1 つだけであるため、元のトランザクションで作業を再開する前に、最新のトランザクションをロールバックまたはコミットする必要があります。

コマンドの最初のセットは、トランザクションを開始します。 New-Item コマンドは、最初のトランザクションの一部です。

2 番目のコマンド セットでは、 Start-Transaction コマンドは Independent パラメーターを使用します。 次の Get-Transaction コマンドは、最新のトランザクションであるアクティブなトランザクションのトランザクション オブジェクトを示しています。 サブスクライバー数は 1 に等しく、トランザクションが無関係であることを示します。

Undo-Transaction コマンドを使用してアクティブなトランザクションをロールバックすると、元のトランザクションが再びアクティブになります。

元のトランザクションの一部である New-ItemProperty コマンドはエラーなしで終了し、元のトランザクションは Complete-Transaction コマンドを使用して完了できます。 その結果、レジストリが変更されます。

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany1" -UseTransaction
PS HKCU:\software> New-Item "ContosoCompany2"
PS HKCU:\software> New-Item "ContosoCompany3" -UseTransaction
PS HKCU:\software> dir contoso*
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
PS HKCU:\Software> dir contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany2                {}

PS HKCU:\Software> Complete-Transaction
PS HKCU:\Software> dir contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany1                     {}
0   0 ContosoCompany2                     {}
0   0 ContosoCompany3                     {}

この例では、トランザクションの進行中に送信されたコマンドをトランザクションに含めることができるか、含めないことを示します。 UseTransaction パラメーターを使用するコマンドのみがトランザクションの一部です。

1 番目と 3 番目の New-Item コマンドは、 UseTransaction パラメーターを使用します。 これらのコマンドは、トランザクションの一部です。 2 番目の New-Item コマンドは UseTransaction パラメーターを使用しないため、トランザクションの一部ではありません。

最初の dir コマンドは、その効果を示しています。 2 番目の New-Item コマンドはすぐに完了しますが、1 番目と 3 番目の New-Item コマンドは、トランザクションがコミットされるまで有効になりません。

Complete-Transaction コマンドは、トランザクションをコミットします。 その結果、2 番目の dir コマンドは、すべての新しい項目がレジストリに追加されたことを示します。

PS C:\> Start-Transaction -Timeout 2

# Wait two minutes...

PS C:\> Get-Transaction
PS C:\> New-Item HKCU:\Software\ContosoCompany -UseTransaction
PS C:\> Start-Transaction -Timeout 2

# Wait two minutes...

PS C:\> > Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   -----------
Error                1                 RolledBack

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

このコマンドは、Start-Transaction の Timeout パラメーターを使用して、2 分以内に完了する必要があるトランザクションを開始します。 タイムアウトが切れたときにトランザクションが完了しない場合、トランザクションは自動的にロールバックされます。

タイムアウトの有効期限が切れると通知されませんが、トランザクション オブジェクトの Status プロパティが RolledBack に設定され、UseTransaction パラメーターを使用するコマンドは失敗します。

None

このコマンドレットに入力をパイプすることはできません。

None

このコマンドレットは出力を生成しません。