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

Start-Transaction cmdlet é 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

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

Esses comandos iniciam e revertem uma transação. Como a transação é revertida, nenhuma alteração é feita no 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

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

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

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 da alteração do valor do parâmetro RollbackPreferences .

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.

Exemplo 4: Use este 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 do uso 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 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ê 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 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 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 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 torna-se ativa novamente.

O New-ItemProperty comando, que faz parte da transação original, termina 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 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 New-Item comandos usam o parâmetro UseTransaction . Esses 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 eficazes 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 termina 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

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.

Parâmetros

-Confirm

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

Tipo:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Independent

Indica que esse cmdlet inicia uma transação independente de quaisquer 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 um efeito somente 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 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 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 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 poderá ser concluída ou desfeita sem afetar a transação original. No entanto, como apenas uma transação pode estar ativa de cada vez, você deve concluir ou reverter a nova transação antes de retomar o trabalho na transação original.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-RollbackPreference

Especifica as condições sob as quais uma transação é revertida automaticamente. Os valores aceitáveis para este 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 predefinido é Error.

Tipo:RollbackSeverity
Valores aceites:Error, TerminatingError, Never
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Timeout

Especifica o tempo máximo, em minutos, em 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
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

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

Saídas

None

Este cmdlet não gera nenhuma saída.