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

Start-Transaction

  • Ссылка
Модуль:
Microsoft.PowerShell.Management

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

Синтаксис

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}

В этом примере показано, как использовать независимый параметр Start-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 , являются частью транзакции.

Первые и третие 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

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

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

Параметры

-Confirm

Запрос подтверждения перед выполнением командлета.

Тип:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Independent

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

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

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

Тип:SwitchParameter
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-RollbackPreference

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

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

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

Тип:RollbackSeverity
Допустимые значения:Error, TerminatingError, Never
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Timeout

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

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

Тип:Int32
Aliases:TimeoutMins
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-WhatIf

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

Тип:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

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

None

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

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

None

Этот командлет не формирует никаких выходных данных.