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 Start-Transaction cmdlet 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 então revertidos.

Por padrão, se algum 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 criados para oferecer 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, este 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 dê suporte ao Windows PowerShell. Outros provedores do Windows PowerShell também podem oferecer suporte a transações.

Somente uma transação pode estar ativa por vez. Se você iniciar uma transação nova e 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.

Start-Transaction cmdlet é um de um conjunto de cmdlets que oferecem 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

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Undo-Transaction

Estes comandos iniciam uma transação e em seguida a revertem. Como a transação é revertida, nenhuma alteração é feita ao registro.

Exemplo 2: Iniciar e concluir uma transação

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction

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

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

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

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 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 erro, o valor padrão de RollbackPreference normalmente é preferido.

Exemplo 4: Usar esse cmdlet enquanto uma transação está em andamento

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

Este exemplo mostra o efeito de usar Start-Transaction enquanto uma transação está em andamento. O efeito é semelhante ao de uma união à transação em andamento.

Embora esse 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 Start-Transaction comando inicia a transação. O primeiro New-Item comando faz parte da transação.

O segundo Start-Transaction comando adiciona um novo assinante à transação. O Get-Transaction comando agora retorna uma transação com uma contagem de assinantes de 2. O segundo New-Item comando 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 Complete-Transaction comandos, um para cada assinante. Se você revertesse a transação a qualquer momento, toda a transação seria revertida para ambos os assinantes.

Exemplo 5: Iniciar uma transação independente enquanto uma está em andamento

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}

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

Apesar de as transações serem logicamente independentes, porque somente uma transação pode ficar 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 New-Item comando faz parte da primeira transação.

No segundo conjunto de comandos, o Start-Transaction comando usa o parâmetro Independent . O Get-Transaction comando 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 Undo-Transaction comando, a transação original se torna ativa novamente.

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

Exemplo 6: Executar comandos que não fazem parte de uma transação

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                     {}

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

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

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

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

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

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

Esse comando usa o parâmetro Timeout of 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.

Parâmetros

-Confirm

Solicita sua 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 todas as 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. Este parâmetro tem efeito somente quando já existe uma transação em andamento na sessão.

Por padrão, se você usar Start-Transaction enquanto uma transação estiver em andamento, o objeto de transação existente será reutilizado e a contagem de assinantes será incrementada. O efeito é semelhante ao de uma união à transação original. Um Undo-Transaction comando reverte toda a transação. Para concluir a transação, você deve inserir um Complete-Transaction comando para cada assinante. Como a maioria das transações que estão em andamento simultaneamente são relacionadas, o padrão é suficiente para a maior parte 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 somente uma transação pode estar ativa por vez, você deve concluir ou reverter a nova transação antes de continuar a trabalhar com a 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 sob as quais uma transação é revertida automaticamente. Os valores aceitáveis para esse parâmetro são:

  • Error A transação é revertida automaticamente se ocorrer um erro de encerramento ou não encerramento.
  • TerminatingError A transação é revertida automaticamente se ocorrer um erro de encerramento.
  • Never 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, pelo qual a transação fica ativa. Quando o tempo limite expira, a transação é revertida automaticamente.

Por padrão, não há tempo limite para transações iniciadas pela 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

Este cmdlet não gera saída.