Start-Transaction

リファレンス

モジュール:: Microsoft.PowerShell.Management

トランザクションを開始します。

構文

Start-Transaction
     [-Timeout <Int32>]
     [-Independent]
     [-RollbackPreference <RollbackSeverity>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

説明

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

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

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

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

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

例

例 1: トランザクションを開始およびロールバックする

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

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

例 2: トランザクションを開始して完了する

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 コマンドが使用されるまで、レジストリに変更は行われません。

例 3: さまざまなロールバック設定を使用する

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 の既定値が通常推奨されます。

例 4: トランザクションの進行中にこのコマンドレットを使用する

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 コマンドを入力する必要があります。任意の時点でトランザクションをロールバックする場合は、両方のサブスクライバーのすべてのトランザクションがロールバックされます。

例 5: 実行中に独立したトランザクションを開始する

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 の独立パラメーターを使用して、別のトランザクションの進行中にトランザクションを開始する効果を示しています。この場合、新しいトランザクションは、元のトランザクションに影響を及ぼすことなくロールバックされます。

これらのトランザクションは論理的に独立していますが、一度に複数のトランザクションを有効にすることはできないので、元のトランザクションに対する作業を再開するには、その前に新しいトランザクションをロールバックするかコミットする必要があります。

最初のコマンドセットを実行すると、トランザクションが開始されます。 New-Item コマンドは、最初のトランザクションの一部です。

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

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

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

例 6: トランザクションに含まれていないコマンドを実行する

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 コマンドは、すべての新しい項目がレジストリに追加されたことを示します。

例 7: 指定した時間内に完了しないトランザクションをロールバックする

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 パラメーターを使用するコマンドは失敗します。

パラメーター

-Confirm

コマンドレットの実行前に確認を求めるメッセージが表示されます。

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Independent

このコマンドレットは、進行中のトランザクションに依存しないトランザクションを開始することを示します。既定では、別のトランザクションの進行中に Start-Transaction を 使用すると、進行中のトランザクションに新しいサブスクライバーが追加されます。このパラメーターが影響を及ぼすのは、トランザクションがセッション内で既に進行中の場合のみです。

既定では、トランザクションの進行中に Start-Transaction を 使用すると、既存のトランザクションオブジェクトが再利用され、サブスクライバー数が増加します。結果は、元のトランザクションの追加とほぼ同じです。 Undo-Transaction コマンドは、トランザクション全体をロールバックします。トランザクションを完了するには、各サブスクライバーに対して Complete-Transaction コマンドを入力する必要があります。同時に進行している大半のトランザクションは互いに関連しているので、ほとんどの場合、既定の設定で十分です。

Independent パラメーターを指定すると、元のトランザクションに影響を与えずに完了または元に戻すことができる新しいトランザクションが作成されます。ただし、一度に複数のトランザクションを有効にすることはできないので、元のトランザクションに対する作業を再開するには、その前に新しいトランザクションを完了するか、ロールバックする必要があります。

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-RollbackPreference

トランザクションが自動的にロールバックされる条件を指定します。このパラメーターの有効値は、次のとおりです。

エラー。終了エラーまたは未終了エラーが発生すると、トランザクションが自動的にロールバックされます。
TerminatingError。終了エラーが発生すると、トランザクションが自動的にロールバックされます。
不可トランザクションは自動的にロールバックされません。

既定値は Error です。

Type:	RollbackSeverity
Accepted values:	Error, TerminatingError, Never
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Timeout

トランザクションが有効である最大時間を分単位で指定します。タイムアウトを過ぎると、トランザクションは自動的にロールバックされます。

既定では、コマンドラインで開始されたトランザクションにタイムアウトはありません。トランザクションがスクリプトによって開始された場合、既定のタイムアウトは 30 分です。

Type:	Int32
Aliases:	TimeoutMins
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

コマンドレットの実行時に発生する内容を示します。このコマンドレットは実行されません。

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Accept pipeline input:	False
Accept wildcard characters:	False

入力

None

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

出力