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 之前进行确认。

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 将不生成任何输出。

相关链接

• Complete-Transaction
• Get-Transaction
• Undo-Transaction
• Use-Transaction