Compartilhar via

Start-Transaction

  • Referência
Módulo:
Microsoft.PowerShell.Management

Inicia uma transação.

Sintaxe

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

Description

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 para 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 executar transações em um provedor, o provedor deve dar suporte a transações. O provedor de Registro do Windows PowerShell no Windows Vista e versões posteriores do sistema operacional Windows dão 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 dê suporte ao Windows PowerShell. Outros provedores do Windows PowerShell também podem dar suporte a transações.

Somente uma transação pode estar ativa por 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 alterações 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.

Exemplos

Exemplo 1: Iniciar e reverter uma transação

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, em seguida, revertem uma transação. Como a transação é revertida, nenhuma alteração é feita no registro.

Exemplo 2: iniciar e concluir uma transação

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, em seguida, completam uma transação. Nenhuma alteração é feita no registro até que o comando Complete-Transaction seja usado.

Exemplo 3: Usar preferências de reversão diferentes

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 de alterar o valor do parâmetro RollbackPreference.

No primeiro conjunto de comandos, start-transaction não usa RollbackPreference. Como resultado, o valor padrão (Erro) é 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 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 é preferencial.

Exemplo 4: Usar este cmdlet enquanto uma transação estiver em andamento

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 de usar 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.

Exemplo 5: iniciar uma transação independente enquanto uma estiver em andamento

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 estiver em andamento. Nesse caso, a nova transação é revertida sem afetar a transação original.

Embora as transações sejam logicamente independentes, porque apenas uma transação pode estar ativa por 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 da 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 Undo-Transaction, a transação original fica ativa novamente.

O comando New-ItemProperty, que faz 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: executar comandos que não fazem parte de uma transação

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 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 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 eficazes 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.

Exemplo 7: Reverter uma transação que não é concluída em um horário especificado

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

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 de transação é definida como RolledBack e os comandos que usam o parâmetro UseTransaction falham.

Parâmetros

-Confirm

Solicita a confirmação antes de executar o cmdlet.

Tipo:SwitchParameter
Aliases:cf
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Independent

Indica que esse cmdlet inicia uma transação independente de qualquer transação em andamento. Por padrão, se você usar de inicialização de transação enquanto outra transação estiver em andamento, um novo assinante será adicionado à transação em andamento. Esse parâmetro só tem efeito quando uma transação já está em andamento na sessão.

Por padrão, se você usar de inicialização de transação enquanto uma transação estiver em andamento, o objeto de transação existente será reutilizado e a contagem de assinantes será incrementada. O efeito é muito parecido com a junção da 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ê especificar o parâmetro Independent, esse cmdlet criará uma nova transação que pode ser concluída ou desfeita sem afetar a transação original. No entanto, como apenas uma transação pode estar ativa por vez, você deve concluir ou reverter a nova transação antes de retomar o trabalho na transação original.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RollbackPreference

Especifica as condições nas quais uma transação é revertida automaticamente. Os valores aceitáveis para este parâmetro são:

  • Erro. A transação será revertida automaticamente se ocorrer um erro de terminação ou não terminação.
  • TerminatingError. A transação será revertida automaticamente se ocorrer um erro de encerramento.
  • Nunca. A transação nunca é revertida automaticamente.

O valor padrão é Error.

Tipo:RollbackSeverity
Valores aceitos:Error, TerminatingError, Never
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Timeout

Especifica o tempo máximo, em minutos, de que a transação está ativa. Quando o tempo limite expira, a transação é revertida automaticamente.

Por padrão, não há 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.

Tipo:Int32
Aliases:TimeoutMins
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

None

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

Saídas

None

Esse cmdlet não gera nenhuma saída.