Start-Transaction

Модуль:: Microsoft.PowerShell.Management Module

Запускает транзакцию.

Синтаксис

Default (По умолчанию)

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

Описание

Командлет Start-Transaction запускает транзакцию, которая представляет собой ряд команд, управляемых как единица. Транзакцию можно завершить или зафиксировать. Кроме того, его можно полностью отменить или откатить, чтобы все данные, измененные транзакцией, восстанавливались в исходном состоянии. Так как команды в транзакции управляются как единица, все команды фиксируются или откатываются все команды.

По умолчанию, если любая команда в транзакции создает ошибку, транзакции откатываются автоматически. Для изменения этого поведения можно использовать параметр RollbackPreference.

Командлеты, используемые в транзакции, должны быть разработаны для поддержки транзакций. Командлеты, поддерживающие транзакции, имеют параметр UseTransaction. Для выполнения транзакций в поставщике поставщик должен поддерживать транзакции. Поставщик реестра Windows PowerShell в Windows Vista и более поздних версиях операционной системы Windows поддерживает транзакции. Можно также использовать класс Microsoft.PowerShell.Commands.Management.TransactedString для включения выражений в транзакции в любой версии системы Windows, поддерживающей Windows PowerShell. Другие поставщики Windows PowerShell также могут поддерживать транзакции.

Одновременно может быть активна только одна транзакция. При запуске новой независимой транзакции во время выполнения транзакции новая транзакция становится активной транзакцией, и перед внесением изменений в исходную транзакцию необходимо зафиксировать или откатить новую транзакцию.

Start-Transaction командлет является одним из наборов командлетов, поддерживающих функцию транзакций в 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. В результате используется значение по умолчанию (ошибка). Если ошибка возникает в команде транзакции, то есть указанный путь не существует, транзакция автоматически откатывается.

Во втором наборе команд Start-Transaction использует RollbackPreference со значением Never. В результате, когда ошибка возникает в команде транзакции, транзакция по-прежнему активна и может быть успешно завершена.

Так как большинство транзакций должны выполняться без ошибок, значение по умолчанию RollbackPreference обычно предпочтительнее.

Пример 4. Использование этого командлета во время выполнения транзакции

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}

В этом примере показано, как использовать параметр IndependentStart-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 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

Эта команда использует параметр TimeoutStart-Transaction для запуска транзакции, которая должна быть завершена в течение двух минут. Если транзакция не завершена, когда истекает время ожидания, она откатывается автоматически.

Когда истекает время ожидания, вы не получите уведомления, но свойство Status объекта транзакции имеет значение RolledBack и команды, использующие параметр UseTransaction сбоем.

Параметры

-Confirm

Запрашивает подтверждение перед запуском cmdlet.

Свойства параметров

Тип:	SwitchParameter
Default value:	False
Поддерживаются подстановочные знаки:	False
DontShow:	False
Aliases:	cf

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Independent

Указывает, что этот командлет запускает транзакцию, которая не зависит от выполняемых транзакций. По умолчанию при использовании Start-Transaction во время выполнения другой транзакции новый подписчик добавляется в транзакцию. Этот параметр действует только в том случае, если транзакция уже выполняется в сеансе.

По умолчанию при использовании Start-Transaction во время выполнения транзакции существующий объект транзакции повторно используется, а число подписчиков увеличивается. Эффект очень похож на присоединение исходной транзакции. Команда Undo-Transaction откатывает всю транзакцию. Чтобы завершить транзакцию, необходимо ввести команду Complete-Transaction для каждого подписчика. Так как большинство выполняемых транзакций одновременно связаны, по умолчанию достаточно для большинства используемых операций.

Если указать параметр Independent, этот командлет создает новую транзакцию, которая может быть завершена или отменена, не затрагивая исходную транзакцию. Однако, так как только одна транзакция может быть активной в один раз, необходимо завершить или откатить новую транзакцию перед возобновлением работы с исходной транзакцией.

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-RollbackPreference

Указывает условия автоматического отката транзакции. Допустимые значения для этого параметра:

Error Откат транзакции выполняется автоматически, если возникает завершающая или не завершающаяся ошибка.
TerminatingError Транзакция откатывается автоматически, если возникает завершающая ошибка.
Never транзакция никогда не откатывается автоматически.

Значение по умолчанию — Error.

Свойства параметров

Тип:	RollbackSeverity
Default value:	None
Допустимые значения:	Error, TerminatingError, Never
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Timeout

Указывает максимальное время в минутах, которое активна транзакция. Когда истекает время ожидания, транзакция автоматически откатывается.

По умолчанию время ожидания для транзакций, запущенных в командной строке, отсутствует. При запуске транзакций скриптом время ожидания по умолчанию составляет 30 минут.

Свойства параметров

Тип:	Int32
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False
Aliases:	TimeoutMins

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-WhatIf

Показывает, что произойдет, если командлет будет запущен. Командлет не запускается.

Свойства параметров

Тип:	SwitchParameter
Default value:	False
Поддерживаются подстановочные знаки:	False
DontShow:	False
Aliases:	wi

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

CommonParameters

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.

Входные данные

None

Входные данные в этот командлет невозможно передать.

Выходные данные

None

Этот командлет не создает выходные данные.

Обратная связь

Были ли сведения на этой странице полезными?

Поделиться через

Start-Transaction

Синтаксис

Default (По умолчанию)

Описание

Примеры

Пример 1. Запуск и откат транзакции

Пример 2. Запуск и завершение транзакции

Пример 3. Использование различных настроек отката

Пример 4. Использование этого командлета во время выполнения транзакции

Пример 5. Запуск независимой транзакции во время выполнения

Пример 6. Выполнение команд, которые не являются частью транзакции

Пример 7. Откат транзакции, которая не завершается в заданное время

Параметры

-Confirm

Свойства параметров

Наборы параметров

-Independent

Свойства параметров

Наборы параметров

-RollbackPreference

Свойства параметров

Наборы параметров

-Timeout

Свойства параметров

Наборы параметров

-WhatIf

Свойства параметров

Наборы параметров

CommonParameters

Входные данные

None

Выходные данные

None

Связанные ссылки

Обратная связь