Start-Transaction

  • リファレンス
モジュール:
Microsoft.PowerShell.Management

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

構文

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

説明

コマンドレットは Start-Transaction トランザクションを開始します。これは、ユニットとして管理される一連のコマンドです。 トランザクションは完了することも、コミットすることもできます。 または、トランザクションによって変更されたデータが元の状態に復元されるように、完全に元に戻すかロールバックすることもできます。 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: トランザクションを開始してロールバックする

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Undo-Transaction

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

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

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction

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

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

Set-Location HKCU:\software
Start-Transaction
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction
Start-Transaction -RollbackPreference never
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction

# Start-Transaction (-rollbackpreference error)

Start-Transaction
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

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)

Start-Transaction -RollbackPreference never
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

New-Item -Path . -Name "ContosoCompany" -UseTransaction

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

# Succeeds

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

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

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

ほとんどのトランザクションはエラーなしで実行する必要があるため、RollbackPreference の既定値が通常推奨されます。

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

Set-Location HKCU:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
Start-Transaction
Get-Transaction
New-Item "ContosoCompany2" -UseTransaction
Complete-Transaction
Complete-Transaction
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: 実行中に独立したトランザクションを開始する

Set-Location HKCU:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
Start-Transaction -Independent
Get-Transaction
Undo-Transaction
New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction
Get-ChildItem contoso*
Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                1                 Active
Undo-Transaction
New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
MyKey
-----
123
Complete-Transaction
Get-ChildItem 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: トランザクションに含まれていないコマンドを実行する

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany1" -UseTransaction
New-Item "ContosoCompany2"
New-Item "ContosoCompany3" -UseTransaction
Get-ChildItem contoso*

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

Complete-Transaction
Get-ChildItem 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 パラメーターを使用しないため、トランザクションの一部ではありません。

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

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

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

Start-Transaction -Timeout 2

# Wait two minutes...

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

# Wait two minutes...

Get-Transaction

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

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

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

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

パラメーター

-Confirm

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

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required: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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RollbackPreference

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

  • Error 終了または終了しないエラーが発生した場合、トランザクションは自動的にロールバックされます。
  • TerminatingError 終了エラーが発生した場合、トランザクションは自動的にロールバックされます。
  • Never トランザクションが自動的にロールバックされることはありません。

既定値は Error です。

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

-Timeout

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

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

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

-WhatIf

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

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

入力

None

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

出力

None

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