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 注册表提供程序支持事务。还可以使用 Microsoft.PowerShell.Commands.Management.TransactedString 类在支持 Windows PowerShell 的任何版本的 Windows 系统上的事务中包含表达式。其他 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 使用 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}

此示例显示使用 Start-Transaction 的 Independent 参数启动事务，而另一个事务正在进行中。在这种情况下，新事务将回滚，而不会影响原始事务。

尽管事务在逻辑上是独立的，因为一次只能有一个事务处于活动状态，但在恢复对原始事务的工作之前，必须回滚或提交最新的事务。

第一组命令启动事务。 New-Item 命令是第一个事务的一部分。

在第二组命令中，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 参数的命令是事务的一部分。

第一和第三个 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。

输出