Start-Transaction

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

O cmdlet Start-Transaction inicia uma transação, que é uma série de comandos gerenciados como uma unidade. Uma transação pode ser concluída ou confirmada. Como alternativa, ele pode ser completamente desfeito ou revertido, para que todos os dados alterados pela transação sejam restaurados ao seu estado original. Como os comandos em uma transação são gerenciados como uma unidade, todos os comandos são confirmados ou todos os comandos são revertidos.

Por padrão, se qualquer comando na transação gerar um erro, as transações serão revertidas automaticamente. Você pode usar o parâmetro RollbackPreference para alterar esse comportamento.

Os cmdlets usados em uma transação devem ser projetados para dar suporte a transações. Os cmdlets que dão suporte a transações têm um parâmetro UseTransaction. Para realizar transações em um provedor, o provedor deve oferecer suporte a transações. O provedor do Registro do Windows PowerShell no Windows Vista e versões posteriores do sistema operacional Windows oferece suporte a transações. Você também pode usar a classe Microsoft.PowerShell.Commands.Management.TransactedString para incluir expressões em transações em qualquer versão do sistema Windows que ofereça suporte ao Windows PowerShell. Outros provedores do Windows PowerShell também podem oferecer suporte a transações.

Apenas uma transação pode estar ativa de cada vez. Se você iniciar uma nova transação independente enquanto uma transação estiver em andamento, a nova transação se tornará a transação ativa e você deverá confirmar ou reverter a nova transação antes de fazer qualquer alteração na transação original.

cmdlet Start-Transaction é um de um conjunto de cmdlets que dão suporte ao recurso de transações no Windows PowerShell. Para obter mais informações, consulte about_Transactions.

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Undo-Transaction

Esses comandos iniciam e revertem uma transação. Como a transação é revertida, nenhuma alteração é feita no registro.

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Complete-Transaction

Esses comandos iniciam e concluem uma transação. Nenhuma alteração é feita no registro até que o comando Complete-Transaction seja usado.

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction -RollbackPreference never
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction

# Start-Transaction (-rollbackpreference error)

PS HKCU:\software> Start-Transaction
PS HKCU:\software> 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

PS HKCU:\software> 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)

PS HKCU:\software> Start-Transaction -RollbackPreference never
PS HKCU:\software> 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
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany                 {}
PS HKCU:\Software> Complete-Transaction

# Succeeds

Este exemplo demonstra o efeito da alteração do RollbackPreference valor do parâmetro.

No primeiro conjunto de comandos, Start-Transaction não usa RollbackPreference. Como resultado, o valor padrão (Error) é usado. Quando ocorre um erro em um comando de transação, ou seja, o caminho especificado não existe, a transação é revertida automaticamente.

No segundo conjunto de comandos, Start-Transaction usa RollbackPreference com um valor de Never. Como resultado, quando ocorre um erro em um comando de transação, a transação ainda está ativa e pode ser concluída com êxito.

Como a maioria das transações deve ser executada sem erros, o valor padrão de RollbackPreference normalmente é preferido.

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction
PS HKCU:\software> Get-Transaction
PS HKCU:\software> New-Item "ContosoCompany2" -UseTransaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\Software> Get-Transaction
RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                2                 Active

Este exemplo mostra o efeito do uso de Start-Transaction enquanto uma transação está em andamento. O efeito é muito parecido com a junção da transação em andamento.

Embora este seja um comando simplificado, esse cenário ocorre frequentemente quando a transação envolve a execução de um script que inclui uma transação completa.

O primeiro comando Start-Transaction inicia a transação. O primeiro comando New-Item faz parte da transação.

O segundo comando Start-Transaction adiciona um novo assinante à transação. O comando Get-Transaction agora retorna uma transação com uma contagem de assinantes de 2. O segundo comando New-Item faz parte da mesma transação.

Nenhuma alteração é feita no registro até que toda a transação seja concluída. Para concluir a transação, você deve inserir dois comandos Complete-Transaction, um para cada assinante. Se você reverter a transação a qualquer momento, toda a transação será revertida para ambos os assinantes.

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction -Independent
PS HKCU:\software> Get-Transaction
PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
PS HKCU:\Software> Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                1                 Active
PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
MyKey
-----
123
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   1 MyCompany                      {MyKey}

Este exemplo mostra o efeito do uso do parâmetro Independent de Start-Transaction para iniciar uma transação enquanto outra transação está em andamento. Nesse caso, a nova transação é revertida sem afetar a transação original.

Embora as transações sejam logicamente independentes, como apenas uma transação pode estar ativa de cada vez, você deve reverter ou confirmar a transação mais recente antes de retomar o trabalho na transação original.

O primeiro conjunto de comandos inicia uma transação. O comando New-Item faz parte da primeira transação.

No segundo conjunto de comandos, o comando Start-Transaction usa o parâmetro Independent. O comando Get-Transaction a seguir mostra o objeto de transação para a transação ativa, que é a mais recente. A contagem de assinantes é igual a 1, o que mostra que as transações não estão relacionadas.

Quando a transação ativa é revertida usando um comando Desfazer-Transação, a transação original torna-se ativa novamente.

O comando New-ItemProperty, que faz parte da transação original, é concluído sem erro e a transação original pode ser concluída usando o comando Complete-Transaction. Como resultado, o registro é alterado.

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany1" -UseTransaction
PS HKCU:\software> New-Item "ContosoCompany2"
PS HKCU:\software> New-Item "ContosoCompany3" -UseTransaction
PS HKCU:\software> dir contoso*
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
PS HKCU:\Software> dir contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany2                {}

PS HKCU:\Software> Complete-Transaction
PS HKCU:\Software> dir contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany1                     {}
0   0 ContosoCompany2                     {}
0   0 ContosoCompany3                     {}

Este exemplo demonstra que os comandos enviados enquanto uma transação está em andamento podem ser incluídos na transação ou não incluídos. Somente comandos que usam o parâmetro UseTransaction fazem parte da transação.

O primeiro e o terceiro comandos New-Item usam o parâmetro UseTransaction. Esses comandos fazem parte da transação. Como o segundo comando New-Item não usa o parâmetro UseTransaction, ele não faz parte da transação.

O primeiro comando dir mostra o efeito. O segundo comando New-Item é concluído imediatamente, mas o primeiro e o terceiro comandos New-Item não são efetivos até que a transação seja confirmada.

O comando Complete-Transaction confirma a transação. Como resultado, o segundo comando dir mostra que todos os novos itens são adicionados ao registro.

PS C:\> Start-Transaction -Timeout 2

# Wait two minutes...

PS C:\> Get-Transaction
PS C:\> New-Item HKCU:\Software\ContosoCompany -UseTransaction
PS C:\> Start-Transaction -Timeout 2

# Wait two minutes...

PS C:\> > Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   -----------
Error                1                 RolledBack

PS C:\> 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

Este comando usa o parâmetro Timeout de Start-Transaction para iniciar uma transação que deve ser concluída em dois minutos. Se a transação não for concluída quando o tempo limite expirar, ela será revertida automaticamente.

Quando o tempo limite expira, você não é notificado, mas a propriedade Status do objeto de transação é definida como RolledBack e os comandos que usam o parâmetro UseTransaction falham.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Não é possível canalizar a entrada para este cmdlet.

Este cmdlet não gera nenhuma saída.