Start-Transaction

参考

模块:: Microsoft.PowerShell.Management

启动事务。

语法

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

说明

Start-Transaction cmdlet 启动事务，事务是作为一个单元进行管理的一系列命令。事务的状态可以是已完成（“已提交”）。或者，也可以是已完全撤消（“已回滚”），以便将由事务更改的所有数据还原为其原始状态。由于事务中的命令作为一个单元进行管理，因此所有命令不是全部提交就是全部回滚。

默认情况下，如果事务中的任何命令发生错误，事务都会自动回滚。可以使用 RollbackPreference 参数更改此行为。

事务中使用的 cmdlet 必须设计为支持事务。支持事务的 cmdlet 具有 UseTransaction 参数。若要通过提供程序执行事务，则该提供程序必须支持事务。 Windows Vista 以及 Windows 更高版本操作系统中的 Windows PowerShell Registry 提供程序支持事务。在支持 Windows PowerShell 的任意版本的 Windows 系统上，也可以使用 Microsoft.PowerShell.Commands.Management.TransactedString 类在事务中包含表达式。其他 Windows PowerShell 提供程序也可以支持事务。

一次只能有一个事务处于活动状态。如果你在事务正在进行时启动一个新的独立事务，则新事务将成为活动事务，你必须先提交或回滚新事务，然后才能对原来的事务进行任何更改。

Start-Transaction cmdlet 是 Windows PowerShell 中支持事务功能的一组 cmdlet 之一。有关详细信息，请参阅 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 使用值为 Never 的 RollbackPreference。因此当事务命令发生错误时，事务仍处于活动状态并且可以成功完成。

由于大多数事务都必须在没有错误的情况下执行，因此 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}

此示例演示了当某一事务正在执行时，使用 Start-Transaction 的 Independent 参数启动另一个事务的效果。在本例中，将回滚新事务，而不影响原来的事务。

虽然事务在逻辑上是独立的，但由于一次只能有一个事务处于活动状态，因此你必须回滚或提交最新事务，然后才能继续处理原来的事务。

第一组命令启动一个事务。 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 之前进行确认。

类型:	SwitchParameter
别名:	cf
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-Independent

指示此 cmdlet 启动一个独立于任何正在执行的事务的事务。默认情况下，如果你在另一个事务正在执行时使用 Start-Transaction，则会向正在执行的事务添加一个新的订阅者。仅当会话中已经在执行某项事务时，此参数才有效。

默认情况下，如果你在事务正在执行时使用 Start-Transaction，则将重用现有事务对象，并且订阅者计数将会递增。这与加入原来事务的效果非常类似。 Undo-Transaction 命令回滚整个事务。若要完成事务，则必须为每个订阅者输入一个 Complete-Transaction 命令。因为同时执行的多数事务都是相关的，所以默认设置可满足大多数用途的要求。

如果指定 Independent 参数，此 cmdlet 将创建一个新事务，它可以在不影响原事务的情况下完成或撤消。但是，由于一次只能有一个事务处于活动状态，因此必须完成或回滚新事务，然后才能继续处理原来的事务。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-RollbackPreference

指定自动回滚事务的条件。此参数的可接受值为：

Error：当发生终止错误或非终止错误时，自动回滚事务。
TerminatingError：当发生终止错误时，自动回滚事务。
Never：从不自动回滚事务。

默认值为 Error。

类型:	RollbackSeverity
接受的值:	Error, TerminatingError, Never
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Timeout

指定事务处于活动状态的最长时间，以分钟为单位。当该超时到期时，将自动回滚事务。

默认情况下，在命令行启动的事务没有超时值。如果事务由脚本启动，则默认超时值为 30 分钟。

类型:	Int32
别名:	TimeoutMins
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-WhatIf

显示运行该 cmdlet 时会发生什么情况。 cmdlet 未运行。

类型:	SwitchParameter
别名:	wi
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

输入

None

不能通过管道将输入传递给此 cmdlet。

输出