Start-Transaction

  • 參考
模組:
Microsoft.PowerShell.Management

啟動交易。

Syntax

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

Description

Cmdlet 會 Start-Transaction 啟動交易，這是一系列以單位方式管理的命令。 交易可以完成或認可。 或者，它可以完全復原或復原，以便交易變更的任何數據都還原至其原始狀態。 由於交易中的命令會以單位方式管理，因此會認可所有命令，或復原所有命令。

根據預設，如果交易中的任何命令產生錯誤，系統會自動回復交易。 您可以使用 RollbackPreference 參數來變更此行為。

交易中使用的 Cmdlet 必須設計為支援交易。 支援交易的 Cmdlet 具有 UseTransaction 參數。 若要在提供者中執行交易，提供者必須支援交易。 Windows Vista 和更新版本的 Windows 操作系統中的 Windows PowerShell 登錄提供者支援交易。 您也可以使用 Microsoft.PowerShell.Commands.Management.TransactedString 類別，將表達式包含在支援 Windows PowerShell 的任何 Windows 系統上的交易中。 其他 Windows PowerShell 提供者也可以支援交易。

一次只能有一個交易作用中。 如果您在交易進行中時啟動新的獨立交易，新交易就會變成使用中交易，而且您必須認可或回復新交易，才能對原始交易進行任何變更。

Start-Transaction Cmdlet 是一組 Cmdlet，可支援 Windows PowerShell 中的交易功能。 如需詳細資訊，請參閱 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）。 當交易命令發生錯誤時，也就是指定的路徑不存在，交易會自動回復。

在第二組命令中， Start-Transaction 使用 RollbackPreference 搭配 Never 值。 因此，當交易命令中發生錯誤時，交易仍然作用中，而且可以順利完成。

由於大部分的交易都必須執行而不會發生錯誤，因此通常慣用 RollbackPreference 的預設值。

範例 4：在交易進行時使用此 Cmdlet

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 個命令是交易的一部分。

第二 Start-Transaction 個命令會將新的訂閱者新增至交易。 命令 Get-Transaction 現在會傳回訂閱者計數為 2 的交易。 第二 New-Item 個命令是相同交易的一部分。

在完成整個交易之前，不會對登錄進行任何變更。 若要完成交易，您必須輸入兩 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}

此範例顯示使用 的 Independent 參數 Start-Transaction 在另一筆交易進行時啟動交易的效果。 在此情況下，新交易會復原，而不會影響原始交易。

雖然交易在邏輯上是獨立的，因為一次只能有一個交易作用中，您必須先復原或認可最新的交易，才能繼續處理原始交易。

第一組命令會啟動交易。 此命令 New-Item 是第一個交易的一部分。

在第二組命令中 Start-Transaction ，命令會使用 Independent 參數。 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 參數的命令是交易的一部分。

第一個和第三 New-Item 個命令會使用 UseTransaction 參數。 這些命令是交易的一部分。 因為第二個 New-Item 命令不使用 UseTransaction 參數，所以它不是交易的一部分。

第一個 Get-ChildItem 命令會顯示效果。 第二 New-Item 個命令會立即完成，但在認可交易之前，第一個和第三 New-Item 個命令才有效。

命令 Complete-Transaction 會認可交易。 因此，第二個 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

此命令使用的 Start-Transaction Timeout 參數啟動必須在兩分鐘內完成的交易。 如果逾時到期時交易未完成，則會自動回復交易。

逾時到期時，您不會收到通知，但 交易物件的 Status 屬性會設定為 RolledBack，而使用 UseTransaction 參數的命令會失敗。

參數

-Confirm

執行 Cmdlet 之前先提示您確認。

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

-Independent

表示此 Cmdlet 會啟動與任何進行中交易無關的交易。 根據預設，如果您在另一個交易進行時使用 Start-Transaction ，則會將新的訂閱者新增至進行中的交易。 只有當交易已在會話中進行時，此參數才會生效。

根據預設，如果您在交易進行時使用 Start-Transaction ，則會重複使用現有的交易物件，並遞增訂閱者計數。 效果就像聯結原始交易一樣。 Undo-Transaction命令會回復整個交易。 若要完成交易，您必須為每個訂閱者輸入 Complete-Transaction 命令。 因為大部分同時進行的交易都相關，因此預設值就足以供大部分使用。

如果您指定 Independent 參數，此 Cmdlet 會建立可完成或復原的新交易，而不會影響原始交易。 不過，由於一次只能有一個交易作用中，因此您必須先完成或回復新交易，才能繼續處理原始交易。

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

顯示執行 Cmdlet 後會發生的情況。 未執行 Cmdlet。

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

輸入

None

您無法使用管線將輸入傳送至此 Cmdlet。

輸出

None

此 Cmdlet 不會產生任何輸出。