啟動交易。

語法

Start-Transaction [-Independent] [-RollbackPreference {<Error> | <TerminatingError> | <Never>}] [-Timeout <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

描述

Start-Transaction Cmdlet 會啟動交易,所謂的交易是指一連串的命令並以一個單元進行管理。任一交易都可以完成 (「認可」),或是完全取消進行 (「復原」),如此一來,交易變更的所有資料都會還原到原始狀態。由於任一交易中的所有命令都會視為一個單元進行管理,因此,所有命令不是全部認可、就是全部復原。

根據預設,如果交易中的任一命令產生錯誤,則會自動復原所有交易,不過,您可以使用 RollbackPreference 參數變更這個行為。

交易中使用的所有 Cmdlet 必須設計以符合支援交易的用意。支援交易的 Cmdlet 都有 UseTransaction 參數。若要在某一提供者執行交易,該提供者必須支援交易。在 Windows Vista 與較新版本的 Windows 中,Windows PowerShell 登錄提供者支援交易。在支援 Windows PowerShell 的任一 Windows 版本中,您也可以使用 Microsoft.PowerShell.Commands.Management.TransactedString 類別,在交易中加入運算式。其他 Windows PowerShell 提供者也支援交易。

每一次只能有一個交易處於現用狀態。如果您某一交易進行中 (尚未完成或尚未復原) 啟動一個新的獨立交易,那麼該項新交易會變成現用交易,而且您必須先認可或復原新交易,才能夠變更原始交易。

在支援 Windows PowerShell 交易功能的一組 Cmdlet 集中,Start-Transaction Cmdlet 是其中一項。如需詳細資訊,請參閱 about_Transactions。

參數

-Independent

啟動與任何作用中交易都沒有關聯的交易。根據預設,如果您在其他交易進行中使用 Start-Transaction,則新訂閱者會新增到進行中的交易。只有在交易已經於工作階段中進行時,這個參數才有作用。

根據預設,如果您在任一交易進行中使用 Start-Transaction,則會重新使用現有交易物件且訂閱者計數會遞增,作用與加入原始交易非常類似。Undo-Transaction 命令會復原整個交易。若要完成交易,您必須為每一個訂閱者輸入 Complete-Transaction 命令。因為大部分同一時間進行的交易都有相關性,所以預設值通常適用於大部分的情況。

如果您使用 Independent 參數,則建立的新交易可以完成或復原,而不會影響原始交易。不過,由於每一次只能有一個現用交易,因此您必須先完成或復原新交易,才能夠繼續操作原始交易。

必要?

false

位置?

named

預設值

Reuse the original transaction object.

接受管線輸入?

false

接受萬用字元?

false

-RollbackPreference <RollbackSeverity>

指定要自動復原哪一個交易的條件。預設值為 "Error"。

有效的值包括:

-- Error:發生終止或非終止的錯誤時,自動復原交易。預設值為 "Error"。

-- 終止錯誤:發生終止或終止的錯誤時,自動復原交易。

-- 永不:永遠不會自動復原交易。

必要?

false

位置?

named

預設值

Error

接受管線輸入?

false

接受萬用字元?

false

-Timeout <int>

指定交易處於現用狀態的時間上限,以分鐘為單位。逾時便會自動復原交易。

根據預設,於命令列啟動的交易沒有逾時限制。以指令碼啟動交易時,預設逾時為 30 分鐘。

必要?

false

位置?

named

預設值

No timeout (infinite)

接受管線輸入?

false

接受萬用字元?

false

-Confirm

在執行命令前先提示確認。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-WhatIf

說明執行命令時將會發生何種情況,但不會實際執行命令。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

<CommonParameters>

這個 Cmdlet 支援一般參數:-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊,請參閱 about_Commonparameters.

輸入和輸出

輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。

輸入

您無法經由管道將輸入輸出至這個 Cmdlet。

輸出

這個 Cmdlet 不會產生任何輸出。

範例 1

C:\PS>cd hkcu:\software

PS HKCU:\software> start-transaction

PS HKCU:\software> new-item MyCompany -UseTransaction

PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction

PS HKCU:\software> undo-transaction

描述
-----------
這些命令會先啟動然後復原交易。因為交易已復原,所以不會對登錄進行任何變更。






範例 2

C:\PS>cd hkcu:\software

PS HKCU:\software> start-transaction

PS HKCU:\software> new-item MyCompany -UseTransaction

PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction

PS HKCU:\software> complete-transaction

描述
-----------
這些命令會先啟動然後完成交易。在使用 Complete-Transaction 命令之前,不會對登錄進行任何變更。






範例 3

C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction

PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction

# Start-Transaction (-rollbackpreference error)

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

PS HKCU:\software> new-item -path . -name MyCompany -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 MyCompany -UseTransaction



# Start-Transaction (-rollbackpreference never)
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<<  -path NoPath -name MyCompany -UseTransaction


PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
  Hive: HKEY_CURRENT_USER\Software

SKC  VC Name                           Property
---  -- ----                           --------
  0   0 MyCompany                      {}

PS HKCU:\Software> complete-transaction
# Succeeds

描述
-----------
這個範例示範變更 RollbackPreference 參數的效果。

在第一組命令中,Start-Transaction 命令不使用 RollbackPreference 參數,所以,會使用預設值 ("Error")。任一交易命令中發生錯誤 (指定的路徑不存在) 時,會自動復原該項交易。

在第二組命令中,Start-Transaction 命令使用值為 "Never" 的 RollbackPreference 參數,因此,任一交易命令中發生錯誤時,該項交易仍然處於現用狀態且會成功完成。

因為大部分交易都可以順利執行而沒有錯誤,所以通常偏好採用 RollbackPreference 參數的預設值。






範例 4

C:\PS>cd HKCU:\software

PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction

PS HKCU:\software> start-transaction
PS HKCU:\software> get-transaction
PS HKCU:\software> new-item MyCompany2 -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 命令也是交易的一部分。

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

在整個交易完成之前,都不會對登錄進行任何變更。若要完成交易,必須輸入兩個 Complete-Transaction 命令,每一個訂閱者都需要一個。如果您要在任何時候復原交易,會同時針對這兩個訂閱者復原整個交易。






範例 5

C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction

PS HKCU:\software> start-transaction -independent
PS HKCU:\software> get-transaction
PS HKCU:\software> undo-transaction

PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*

PS HKCU:\Software> get-transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                1                 Active

PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction

MyKey
-----
123

PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*

   Hive: HKEY_CURRENT_USER\Software

SKC  VC Name                           Property
---  -- ----                           --------
  0   1 MyCompany                      {MyKey}

描述
-----------
這個範例示範在其他交易進行時,使用 Start-Transaction 的 Independent 參數啟動另一個交易的作用。在這個案例中,會復原新交易而不會影響原始交易。

雖然就邏輯的觀點而言,這些交易都是獨立的,但是因為每次只能有一項處於現用狀態的交易,所以您必須先復原或認可最新的交易,才能夠繼續操作原始交易。

第一組命令啟動交易,而 New-Item 命令也是第一項交易的一部分。

在第二組命令中,Start-Transaction 命令使用 Independent 參數,而緊接著的 Get-Transaction 命令示範現用交易 (最新的一項) 的交易物件。訂閱者計數為 1,表示這些交易之間並沒有關聯性。

使用 Undo-Transaction 命令復原現用交易時,原始交易會再次變為現用狀態。

屬於原始交易的 New-ItemProperty 命令會順利完成、沒有錯誤發生,而原始交易可以透過 Complete-Transaction 命令完成,所以,登錄會變更。






範例 6

C:\PS>cd hkcu:\software

PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany1 -UseTransaction
PS HKCU:\software> new-item MyCompany2 
PS HKCU:\software> new-item MyCompany3 -UseTransaction

PS HKCU:\software> dir my*

PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*

PS HKCU:\Software> dir my*

   Hive: HKEY_CURRENT_USER\Software

SKC  VC Name                           Property
---  -- ----                           --------
  0   0 MyCompany2                     {}

PS HKCU:\Software> complete-transaction

PS HKCU:\Software> dir my*

   Hive: HKEY_CURRENT_USER\Software

SKC  VC Name                           Property
---  -- ----                           --------
  0   0 MyCompany1                     {}
  0   0 MyCompany2                     {}
  0   0 MyCompany3                     {}

描述
-----------
這個範例示範於交易進行中提交的命令,不一定會包含在交易中的情況。只有使用 UseTransaction 參數的命令才屬於交易的一部分。

第一個與第三個 New-Item 命令使用 UseTransaction 參數。這些命令都屬於交易的一部分。因為第二個 New-Item 命令不使用 UseTransaction 參數,所以這個命令不是交易的一部分。

第一個 "dir" 命令顯示作用。第二個 New-Item 命令會立即完成,但是第一個與第三個 New-Item 命令在交易認可之前,都不會發生作用。

Complete-Transaction 命令會認可交易,因此,第二個 "dir" 命令顯示所有新項目都已新增到登錄中。






範例 7

C:\PS>start-transaction -timeout 2

# Wait two minutes...

C:\PS> get-transaction

C:\PS> new-item HKCU:\Software\MyCompany -UseTransaction

C:\PS> start-transaction -timeout 2

# Wait two minutes...

C:\PS>> get-transaction

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


C:\PS> new-item HKCU:\Software\MyCompany -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 參數的命令會失敗。






請參閱




目錄