about_Transactions
Descrição breve
Descreve como gerenciar operações transacionadas no PowerShell.
Descrição longa
Há suporte para transações no PowerShell a partir do PowerShell 2.0. Esse recurso permite que você inicie uma transação, indique quais comandos fazem parte da transação e confirme ou reverta uma transação.
No PowerShell, uma transação é um conjunto de um ou mais comandos gerenciados como uma unidade lógica. Uma transação pode ser concluída ("confirmada"), o que altera os dados afetados pela transação. Ou uma transação pode ser completamente desfeita ("revertida") para que os dados afetados não sejam alterados pela transação.
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.
As transações são amplamente utilizadas no processamento de dados, principalmente em operações de banco de dados e para transações financeiras. As transações são usadas com mais frequência quando o pior cenário para um conjunto de comandos não é que todos eles falhem, mas que alguns comandos sejam bem-sucedidos enquanto outros falham, deixando o sistema em um estado danificado, falso ou não interpretável que é difícil de reparar.
Cmdlets de transação
O PowerShell inclui vários cmdlets projetados para gerenciar transações.
Start-Transaction: Inicia uma nova transação.Use-Transaction: Adiciona um comando ou expressão à transação. O comando deve usar objetos habilitados para transação.Undo-Transaction: Reverte a transação para que nenhum dado seja alterado pela transação.Complete-Transaction: Confirma a transação. Os dados afetados pela transação são alterados.Get-Transaction: Obtém informações sobre a transação ativa.
Para obter uma lista de cmdlets de transação, digite:
Get-Command *transaction
Para obter informações detalhadas sobre os cmdlets, digite:
Get-Help Use-Transaction -Detailed
Elementos habilitados para transação
Para participar de uma transação, o cmdlet e o provedor devem dar suporte a transações. Esse recurso é incorporado aos objetos afetados pela transação.
O provedor do Registro do PowerShell dá suporte a transações no Windows. O objeto TransactedString funciona com qualquer sistema operacional que executa o PowerShell.
Outros provedores do PowerShell podem dar suporte a transações. Para localizar os provedores do PowerShell em sua sessão que dão suporte a transações, use o seguinte comando para localizar o valor Transactions na propriedade Capabilities dos provedores:
Get-PSProvider | Where-Object {$_.Capabilities -like "*transactions*"}
Para obter mais informações sobre um provedor, consulte a Ajuda do provedor. Para obter ajuda do provedor, digite:
Get-Help <provider-name>
Por exemplo, para obter Ajuda para o provedor de Registro, digite:
Get-Help registry
O parâmetro UseTransaction
Os cmdlets que podem dar suporte a transações têm um parâmetro UseTransaction . Esse parâmetro inclui o comando na transação ativa. Você pode usar o nome completo do parâmetro ou seu alias, usetx.
O parâmetro pode ser usado somente quando a sessão contém uma transação ativa. Se você inserir um comando com o parâmetro UseTransaction quando não houver nenhuma transação ativa, o comando falhará.
Para localizar cmdlets com o parâmetro UseTransaction , digite:
Get-Help * -Parameter UseTransaction
No núcleo do PowerShell, todos os cmdlets projetados para funcionar com provedores do PowerShell dão suporte a transações. Como resultado, você pode usar os cmdlets do provedor para gerenciar transações.
Para obter mais informações sobre provedores do PowerShell, consulte about_Providers.
O objeto de transação
As transações são representadas no PowerShell por um objeto de transação, System.Management.Automation.Transaction.
O objeto tem as seguintes propriedades:
RollbackPreference: contém a preferência de rollback definida para a transação atual. Você pode definir a preferência de reversão ao usar
Start-Transactionpara iniciar a transação.A preferência de rollback determina as condições sob as quais a transação é revertida automaticamente. Os valores válidos são
Error,TerminatingErroreNever. O valor padrão éError.Status: contém o status atual da transação. Os valores válidos são
Active,CommittedeRolledBack.SubscriberCount: contém o número de assinantes da transação. Um assinante é adicionado a uma transação quando você inicia uma transação enquanto outra transação está em andamento. A contagem de assinantes é diminuída quando um assinante confirma a transação.
Transações ativas
No PowerShell, apenas uma transação está ativa por vez e você pode gerenciar apenas a transação ativa. Várias transações podem estar em andamento na mesma sessão ao mesmo tempo, mas apenas a transação iniciada mais recentemente está ativa.
Como resultado, você não pode especificar uma transação específica ao usar os cmdlets de transação. Os comandos sempre se aplicam à transação ativa.
Isso é mais evidente no comportamento do Get-Transaction cmdlet. Quando você insere um Get-Transaction comando, Get-Transaction sempre obtém apenas um objeto de transação. Esse objeto é o objeto que representa a transação ativa.
Para gerenciar uma transação diferente, você deve primeiro concluir a transação ativa, confirmando-a ou revertendo-a. Quando você faz isso, a transação anterior se torna ativa automaticamente. As transações tornam-se ativas na ordem inversa da qual são iniciadas, de modo que a transação iniciada mais recentemente esteja sempre ativa.
Assinantes e transações independentes
Se você iniciar uma transação enquanto outra transação estiver em andamento, por padrão, o PowerShell não iniciará uma nova transação. Em vez disso, ele adiciona um "assinante" à transação atual.
Quando uma transação tem vários assinantes, um único Undo-Transaction comando a qualquer momento reverte toda a transação para todos os assinantes.
No entanto, para confirmar a transação, você deve inserir um Complete-Transaction comando para cada assinante.
Para localizar o número de assinantes de uma transação, verifique a propriedade SubscriberCount do objeto de transação. Por exemplo, o comando a seguir usa o Get-Transaction cmdlet para obter o valor da propriedade SubscriberCount da transação ativa:
(Get-Transaction).SubscriberCount
Adicionar um assinante é o comportamento padrão porque a maioria das transações iniciadas enquanto outra transação está em andamento está relacionada à transação original. No modelo típico, um script que contém uma transação chama um script auxiliar que contém sua própria transação. Como as transações estão relacionadas, elas devem ser revertidas ou confirmadas como uma unidade.
No entanto, você pode iniciar uma transação independente da transação atual usando o Start-Transaction parâmetro Independent do cmdlet.
Quando você inicia uma transação independente, Start-Transaction o cria um novo objeto de transação e a nova transação se torna a transação ativa. A transação independente pode ser confirmada ou revertida sem afetar a transação original.
Quando a transação independente é concluída (confirmada ou revertida), a transação original se torna a transação ativa novamente.
Alterando dados
Quando você usa transações para alterar dados, os dados afetados pela transação não são alterados até que você confirme a transação. No entanto, os mesmos dados podem ser alterados por comandos que não fazem parte da transação.
Lembre-se disso ao usar transações para gerenciar dados compartilhados. Normalmente, os bancos de dados têm mecanismos que bloqueiam os dados enquanto você está trabalhando neles, impedindo que outros usuários e outros comandos, scripts e funções os alterem.
No entanto, o bloqueio é um recurso do banco de dados. Não está relacionado a transações. Se você estiver trabalhando em um sistema de arquivos habilitado para transação ou outro armazenamento de dados, os dados poderão ser alterados enquanto a transação estiver em andamento.
Exemplos
Os exemplos nesta seção usam o provedor do Registro do PowerShell e pressupõem que você esteja familiarizado com ele. Para obter informações sobre o provedor do Registro, digite Get-Help registry.
Exemplo 1: Confirmando uma transação
Para criar uma transação, use o Start-Transaction cmdlet. O comando a seguir inicia uma transação com as configurações padrão.
Start-Transaction
Para incluir comandos na transação, use o parâmetro UseTransaction do cmdlet. Por padrão, os comandos não são incluídos na transação,
Por exemplo, o comando a seguir, que define o local atual na chave Software da HKCU: unidade, não está incluído na transação.
cd hkcu:\Software
O comando a seguir, que cria a chave MyCompany, usa o parâmetro UseTransaction do New-Item cmdlet para incluir o comando na transação ativa.
New-Item MyCompany -UseTransaction
O comando retorna um objeto que representa a nova chave, mas como o comando faz parte da transação, o Registro ainda não foi alterado.
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany {}
Para confirmar a transação, use o Complete-Transaction cmdlet. Como ele sempre afeta a transação ativa, você não pode especificar a transação.
Complete-Transaction
Como resultado, a MyCompany chave é adicionada ao registro.
dir m*
Hive: HKEY_CURRENT_USER\software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany {}
Exemplo 2: Reverter uma transação
Para criar uma transação, use o Start-Transaction cmdlet. O comando a seguir inicia uma transação com as configurações padrão.
Start-Transaction
O comando a seguir, que cria a chave MyOtherCompany, usa o parâmetro UseTransaction do New-Item cmdlet para incluir o comando na transação ativa.
New-Item MyOtherCompany -UseTransaction
O comando retorna um objeto que representa a nova chave, mas como o comando faz parte da transação, o Registro ainda não foi alterado.
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyOtherCompany {}
Para reverter a transação, use o Undo-Transaction cmdlet. Como ele sempre afeta a transação ativa, você não especifica a transação.
Undo-Transaction
O resultado é que a MyOtherCompany chave não é adicionada ao Registro.
dir m*
Hive: HKEY_CURRENT_USER\software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany {}
Exemplo 3: Visualizando uma transação
Normalmente, os comandos usados em uma transação alteram os dados. No entanto, os comandos que obtêm dados também são úteis em uma transação, porque obtêm dados dentro da transação. Isso fornece uma visualização das alterações que a confirmação da transação causaria.
O exemplo a seguir mostra como usar o Get-ChildItem comando (o alias é dir) para visualizar as alterações em uma transação.
O comando a seguir inicia uma transação.
Start-Transaction
O comando a seguir usa o New-ItemProperty cmdlet para adicionar a entrada do MyKey Registro à chave MyCompany. O comando usa o parâmetro UseTransaction para incluir o comando na transação.
New-Itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction
O comando retorna um objeto que representa a nova entrada do Registro, mas a entrada do Registro não é alterada.
MyKey
-----
123
Para obter os itens que estão atualmente no registro, use um Get-ChildItem comando (dir) sem o parâmetro UseTransaction. O comando a seguir obtém itens que começam com "M".
dir m*
O resultado mostra que nenhuma entrada ainda foi adicionada à MyCompany chave.
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany {}
Para visualizar o efeito da confirmação da transação, insira um Get-ChildItem comando (dir) com o parâmetro UseTransaction. Esse comando tem uma exibição dos dados de dentro da transação.
dir m* -useTransaction
O resultado mostra que, se a transação for confirmada, a MyKey entrada será adicionada à MyCompany chave.
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 1 MyCompany {MyKey}
Exemplo 4: Combinando comandos transacionados e não transacionados
Você pode inserir comandos não transacionados durante uma transação. Os comandos não transacionados afetam os dados imediatamente, mas não afetam a transação.
O comando a seguir inicia uma transação na HKCU:\Software chave do Registro.
Start-Transaction
Os próximos três comandos usam o New-Item cmdlet para adicionar chaves ao Registro.
O primeiro e o terceiro comandos usam o parâmetro UseTransaction para incluir os comandos na transação. O segundo comando omite o parâmetro. Como o segundo comando não está incluído na transação, ele entra em vigor imediatamente.
New-Item MyCompany1 -UseTransaction
New-Item MyCompany2
New-Item MyCompany3 -UseTransaction
Para exibir o estado atual do Registro, use um Get-ChildItem comando (dir) sem o parâmetro UseTransaction. Esse comando obtém itens que começam com M.
dir m*
O resultado mostra que a MyCompany2 chave é adicionada ao Registro, mas as MyCompany1 chaves e MyCompany3 , que fazem parte da transação, não são adicionadas.
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany2 {}
O comando a seguir confirma a transação.
Complete-Transaction
Agora, as chaves que foram adicionadas como parte da transação aparecem no registro.
dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany1 {}
0 0 MyCompany2 {}
0 0 MyCompany3 {}
Exemplo 5: Usando a reversão automática
Quando um comando em uma transação gera um erro de qualquer tipo, a transação é revertida automaticamente.
Esse comportamento padrão foi projetado para scripts que executam transações. Os scripts geralmente são bem testados e incluem lógica de tratamento de erros, portanto, erros não são esperados e devem encerrar a transação.
O primeiro comando inicia uma transação na HKCU:\Software chave do Registro.
Start-Transaction
O comando a seguir usa o New-Item cmdlet para adicionar a MyCompany chave ao Registro. O comando usa o parâmetro UseTransaction (o alias é usetx) para incluir o comando na transação.
New-Item MyCompany -usetx
Como a MyCompany chave já existe no registro, o comando falha e a transação é revertida.
New-Item : A key at this path already exists
At line:1 char:9
+ New-Item <<<< MyCompany -usetx
Um Get-Transaction comando confirma que a transação foi revertida e que o SubscriberCount é 0.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 0 RolledBack
Exemplo 6: Alterando a preferência de reversão
Se você quiser que a transação seja mais tolerante a erros, poderá usar o parâmetro RollbackPreference de Start-Transaction para alterar a preferência.
O comando a seguir inicia uma transação com uma preferência de reversão de Never.
Start-Transaction -RollbackPreference Never
Nesse caso, quando o comando falha, a transação não é revertida automaticamente.
New-Item MyCompany -usetx
New-Item : A key at this path already exists
At line:1 char:9
+ New-Item <<<< MyCompany -usetx
Como a transação ainda está ativa, você pode reenviar o comando como parte da transação.
New-Item MyOtherCompany -usetx
Exemplo 7: usando o Use-Transaction cmdlet
O Use-Transaction cmdlet permite que você faça scripts diretos em objetos do Microsoft .NET Framework habilitados para transação. Use-Transaction usa um bloco de script que só pode conter comandos e expressões que usam objetos .NET Framework habilitados para transação, como instâncias da classe Microsoft.PowerShell.Commands.Management.TransactedString .
O comando a seguir inicia uma transação.
Start-Transaction
O comando a seguir New-Object cria uma instância da classe TransactedString e a salva na $t variável.
$t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
O comando a seguir usa o método Append do objeto TransactedString para adicionar texto à cadeia de caracteres. Como o comando não faz parte da transação, a alteração entra em vigor imediatamente.
$t.append("Windows")
O comando a seguir usa o mesmo método Append para adicionar texto, mas adiciona o texto como parte da transação. O comando é colocado entre chaves e é definido como o valor do parâmetro ScriptBlock de Use-Transaction. O parâmetro UseTransaction (usetx) é necessário.
Use-Transaction {$t.append(" PowerShell")} -usetx
Para ver o conteúdo atual da cadeia de caracteres transacionada em $t, use o ToString método do objeto TransactedString .
$t.tostring()
A saída mostra que apenas as alterações não transacionadas são efetivas.
Windows
Para ver o conteúdo atual da cadeia de caracteres transacionada em $t de dentro da transação, insira a expressão em um Use-Transaction comando.
Use-Transaction {$t.tostring()} -usetx
A saída mostra a visualização da transação.
PowerShell
O comando a seguir confirma a transação.
Complete-Transaction
Para ver a string final:
$t.tostring()
PowerShell
Exemplo 8: Gerenciando transações de vários assinantes
Quando você inicia uma transação enquanto outra transação está em andamento, o PowerShell não cria uma segunda transação por padrão. Em vez disso, ele adiciona um assinante à transação atual.
Este exemplo mostra como exibir e gerenciar uma transação de vários assinantes.
Comece iniciando uma transação na HKCU:\Software chave.
Start-Transaction
O comando a seguir usa o Get-Transaction comando para obter a transação ativa.
Get-Transaction
O resultado mostra o objeto que representa a transação ativa.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
O comando a seguir adiciona a chave MyCompany ao registro. O comando usa o parâmetro UseTransaction para incluir o comando na transação.
New-Item MyCompany -UseTransaction
O comando a seguir usa o Start-Transaction comando para iniciar uma transação. Embora esse comando seja digitado no prompt de comando, é mais provável que esse cenário aconteça quando você executa um script que contém uma transação.
Start-Transaction
Um Get-Transaction comando mostra que a contagem de assinantes no objeto de transação é incrementada. O valor agora é 2.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 Active
O próximo comando usa o New-ItemProperty cmdlet para adicionar a entrada do Registro MyKey à chave MyCompany. Ele usa o parâmetro UseTransaction para incluir o comando na transação.
New-ItemProperty -path MyCompany -name MyKey -UseTransaction
A chave MyCompany não existe no registro, mas esse comando é bem-sucedido porque os dois comandos fazem parte da mesma transação.
O comando a seguir confirma a transação. Se ele revertesse a transação, a transação seria revertida para todos os assinantes.
Complete-Transaction
Um Get-Transaction comando mostra que a contagem de assinantes no objeto de transação é 1, mas o valor de Status ainda é Ativo (não Confirmado).
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
Para concluir a confirmação da transação, insira um segundo comando Complete-Transaction. Para confirmar uma transação de vários assinantes, você deve inserir um Complete-Transaction comando para cada Start-Transaction comando.
Complete-Transaction
Outro Get-Transaction comando mostra que a transação foi confirmada.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 0 Committed
Exemplo 9: Gerenciando transações independentes
Ao iniciar uma transação enquanto outra transação está em andamento, você pode usar o parâmetro Independent of Start-Transaction para tornar a nova transação independente da transação original.
Ao fazer isso, Start-Transaction o cria um novo objeto de transação e torna a nova transação a transação ativa.
Comece iniciando uma transação na HKCU:\Software chave.
Start-Transaction
O comando a seguir usa o Get-Transaction comando para obter a transação ativa.
Get-Transaction
O resultado mostra o objeto que representa a transação ativa.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
O comando a seguir adiciona a chave do Registro MyCompany como parte da transação. Ele usa o parâmetro UseTransaction (usetx) para incluir o comando na transação ativa.
New-Item MyCompany -use
O comando a seguir inicia uma nova transação. O comando usa o parâmetro Independent para indicar que essa transação não é um assinante da transação ativa.
Start-Transaction -Independent
Quando você cria uma transação independente, a nova transação (criada mais recentemente) se torna a transação ativa. Você pode usar um Get-Transaction comando para obter a transação ativa.
Get-Transaction
Observe que o SubscriberCount da transação é 1, indicando que não há outros assinantes e que a transação é nova.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
A nova transação deve ser concluída (confirmada ou revertida) antes que você possa gerenciar a transação original.
O comando a seguir adiciona a chave MyOtherCompany ao registro. Ele usa o parâmetro UseTransaction (usetx) para incluir o comando na transação ativa.
New-Item MyOtherCompany -usetx
Agora, reverta a transação. Se houvesse uma única transação com dois assinantes, reverter a transação reverteria toda a transação para todos os assinantes.
No entanto, como essas transações são independentes, a reversão da transação mais recente cancela as alterações do Registro e torna a transação original a transação ativa.
Undo-Transaction
Um Get-Transaction comando confirma que a transação original ainda está ativa na sessão.
Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
O comando a seguir confirma a transação ativa.
Complete-Transaction
Um Get-ChildItem comando mostra que o registro foi alterado.
dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany {}
