Start-Transaction
Inicia uma transação.
Sintaxe
Start-Transaction [-Independent] [-RollbackPreference {<Error> | <TerminatingError> | <Never>}] [-Timeout <int>] [-Confirm] [-WhatIf] [<CommonParameters>]
Descrição
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 ("confirmada") ou desfeita ("revertida"), para que qualquer dado alterado pela transação seja restaurado ao seu estado original. Como os comandos em uma transação são gerenciados como uma unidade, todos os comandos são confirmados ou revertidos.
Por padrão, as transações são revertidas automaticamente se qualquer comando na transação gerar um erro, mas você pode usar o parâmetro RollbackPreference para alterar esse comportamento.
Os cmdlets usados na transição devem ser desenvolvidos com suporte para transações. Os cmdlets com suporte para transações têm um parâmetro UseTransaction. Para realizar transações em um provedor, o provedor deve ter suporte para transações. O provedor Registry do Windows PowerShell no Windows Vista e versões mais recentes do Windows tem suporte para 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 Windows que tenha suporte para o Windows PowerShell. Outros provedores do Windows PowerShell também têm suporte para transações.
Apenas uma transação pode estar ativa por vez. Se você iniciar uma transação nova e independente enquanto outra estiver em andamento (nem concluída, nem desfeita), a nova transação se tornará a transação ativa e você deverá confirmar ou reverter a nova transação antes de fazer alterações na transação original.
O cmdlet Start-Transaction faz parte 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.
Parâmetros
-Independent
Inicia uma transação que independe das transações em andamento. Por padrão, se você usar Start-Transaction enquanto outra transação estiver em andamento, um novo assinante será adicionado à transação em andamento. Esse parâmetro tem efeito apenas quando uma transação já está em andamento na sessão.
Por padrão, se você usar Start-Transaction enquanto uma transação estiver em andamento, o objeto da transação existente será reutilizado e a contagem de assinantes será incrementada. O efeito é semelhante a ingressar na transação original. Um comando Undo-Transaction reverte toda a transação. Para concluir a transação, você deve inserir um comando Complete-Transaction para cada assinante. Como a maioria das transações que estão em andamento ao mesmo tempo estão relacionadas, o padrão é suficiente para a maioria dos usos.
Se você usar o parâmetro Independent, será criada uma nova transação que pode ser concluída ou desfeita sem afetar a transação original. No entanto, como só uma transação pode estar ativa por vez, você deve concluir ou reverter a nova transação antes de continuar a trabalhar na transação original.
Necessário? |
false |
Posição? |
named |
Valor padrão |
Reutiliza o objeto da transação original. |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-RollbackPreference <RollbackSeverity>
Especifica as condições nas quais uma transação é revertida automaticamente. O valor padrão é “Error”.
Os valores válidos são:
-- Error: a transação é revertida automaticamente se ocorrer um erro de encerramento ou de não encerramento. O valor padrão é “Error”.
-- Terminating error: a transação é revertida automaticamente se ocorrer um erro de encerramento.
-- Never: a transação nunca é revertida automaticamente.
Necessário? |
false |
Posição? |
named |
Valor padrão |
Error |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Timeout <int>
Especifica o máximo de tempo, em minutos, que a transação fica ativa. Quando o tempo limite expira, a transação é revertida automaticamente.
Por padrão, não existe tempo limite para transações iniciadas na linha de comando. Quando as transações são iniciadas por um script, o tempo limite padrão é de 30 minutos.
Necessário? |
false |
Posição? |
named |
Valor padrão |
Sem tempo limite (infinito) |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Confirm
Solicita confirmação antes da execução do comando.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-WhatIf
Descreve o que aconteceria se você executasse o comando, sem executá-lo de fato.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
Nenhum Você não pode canalizar a entrada para este cmdlet. |
Saídas |
Nenhum Esse cmdlet não gera nenhuma saída. |
Exemplo 1
C:\PS>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> undo-transaction
Descrição
-----------
Estes comandos iniciam e revertem uma transação. Como a transação é revertida, não há alterações no Registro.
Exemplo 2
C:\PS>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> complete-transaction
Descrição
-----------
Estes comandos iniciam e concluem uma transação. Nenhuma alteração é feita no Registro até que o comando Complete-Transaction seja usado.
Exemplo 3
C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
# Start-Transaction (-rollbackpreference error)
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -Name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -path NoPath -Name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -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 MyCompany -UseTransaction
# Start-Transaction (-rollbackpreference never)
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany {}
PS HKCU:\Software> complete-transaction
# Succeeds
Descrição
-----------
Este exemplo demonstra o efeito da alteração do valor do parâmetro RollbackPreference.
No primeiro conjunto de comandos, o comando Start-Transaction não usa o parâmetro RollbackPreference. Como resultado, o valor padrão ("Error") é usado. Quando um erro ocorre em um comando de transação (o caminho especificado não existe), a transação é automaticamente revertida.
No segundo conjunto de comandos, o comando Start-Transaction usa o parâmetro RollbackPreference com o valor "Never". Como resultado, quando um erro ocorre 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 realizada sem erros, o valor padrão do parâmetro RollbackPreference é normalmente preferido.
Exemplo 4
C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> start-transaction
PS HKCU:\software> get-transaction
PS HKCU:\software> new-item MyCompany2 -UseTransaction
PS HKCU:\software> complete-transaction
PS HKCU:\software> complete-transaction
PS HKCU:\Software> Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 Active
Descrição
-----------
Este exemplo mostra o efeito de usar o comando Start-Transaction enquanto uma transação está em andamento. O efeito é semelhante a ingressar na transação original.
Apesar de ser um comando simplificado, esse cenário é muito comum quando a transação envolve a execução de um script que inclui uma transação concluída.
O primeiro comando Start-Transaction inicia a transação. O primeiro comando New-Item é 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 assinante igual a 2. O segundo comando New-Item é parte da mesma transação.
Nenhuma alteração é feita no Registro até que a transação inteira seja concluída. Para concluir a transação, você deve inserir dois comandos Complete-Transaction, um para cada assinante. Se você for reverter a transação em algum ponto, a transação inteira será revertida para os dois assinantes.
Exemplo 5
C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> start-transaction -independent
PS HKCU:\software> get-transaction
PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
PS HKCU:\Software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
MyKey
-----
123
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 1 MyCompany {MyKey}
Descrição
-----------
Este exemplo mostra o efeito de usar o 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.
Apesar de as transações serem logicamente independentes, como apenas uma transação pode estar ativa por vez, você deve reverter ou confirmar a transação mais recente antes de continuar a trabalhar na transação original.
O primeiro conjunto de comandos inicia uma transação. O comando New-Item é 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 (a mais nova). A contagem de assinantes é igual a 1, mostrando que as transações não são relacionadas.
Quando a transação ativa é revertida usando um comando Undo-Transaction, a transação original torna-se ativa novamente.
O comando New-ItemProperty, que é parte da transação original, é concluído sem erros e a transação original pode ser concluída usando o comando Complete-Transaction. Como resultado, o Registro é alterado.
Exemplo 6
C:\PS>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany1 -UseTransaction
PS HKCU:\software> new-item MyCompany2
PS HKCU:\software> new-item MyCompany3 -UseTransaction
PS HKCU:\software> dir my*
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
PS HKCU:\Software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany2 {}
PS HKCU:\Software> complete-transaction
PS HKCU:\Software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany1 {}
0 0 MyCompany2 {}
0 0 MyCompany3 {}
Descrição
-----------
Este exemplo demonstra que os comandos enviados enquanto uma transação está em andamento podem ser ou não incluídos na transação. Apenas os 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 é 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 só entram em vigor quando a transação é confirmada.
O comando Complete-Transaction confirma a transação. Como resultado, o segundo comando “dir” mostra que todos os novos itens foram adicionados ao Registro.
Exemplo 7
C:\PS>start-transaction -timeout 2
# Wait two minutes...
C:\PS> get-transaction
C:\PS> new-item HKCU:\Software\MyCompany -UseTransaction
C:\PS> start-transaction -timeout 2
# Wait two minutes...
C:\PS>> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- -----------
Error 1 RolledBack
C:\PS> new-item HKCU:\Software\MyCompany -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
Descrição
-----------
Esse comando usa o parâmetro Timeout de Start-Transaction para iniciar uma transação que deve ser concluída dentro de 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 da transação é definida como RolledBack e os comandos que usam o parâmetro UseTransaction falham.
Consulte também
Conceitos
about_Transactions
Get-Transaction
Complete-Transaction
Undo-Transaction
Use-Transaction