about_Transactions
Descrição breve
Descreve como gerenciar operações transacionadas no PowerShell.
Descrição longa
As transações têm suporte no PowerShell a partir do PowerShell 2.0. Esse recurso permite iniciar uma transação, indicar quais comandos fazem parte da transação e confirmar ou reverter uma transação.
SOBRE AS TRANSAÇÕES
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 mais frequentemente usadas 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 ininterpretá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.
- Desfazer-Transação: 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 oferecer suporte a transações. Esse recurso é incorporado aos objetos afetados pela transação.
O provedor do Registro do PowerShell oferece suporte a transações no Windows Vista. O objeto TransactedString (Microsoft.PowerShell.Commands.Management.TransactedString) funciona com qualquer sistema operacional que execute o PowerShell.
Outros provedores do PowerShell podem oferecer suporte a transações. Para localizar os provedores do PowerShell em sua sessão que oferecem suporte a transações, use o seguinte comando para localizar o valor "Transações" na propriedade Capabilities dos provedores:
get-psprovider | where {$_.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 oferecer 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 trabalhar com provedores do PowerShell oferecem 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 o conjunto de preferências de reversão para a transação atual. Você pode definir a preferência de reversão ao usar Start-Transaction para iniciar a transação.
A preferência de reversão determina as condições sob as quais a transação é revertida automaticamente. Os valores válidos são Error, TerminatingError e Never. O valor padrão é Error.
Status: contém o status atual da transação. Os valores válidos são Active, Commit e RolledBack.
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 cmdlet Get-Transaction. Quando você insere um comando Get-Transaction, 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ê fizer isso, a transação anterior se tornará ativa automaticamente. As transações tornam-se ativas no sentido inverso da ordem em que 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 comando Desfazer Transação a qualquer momento reverte toda a transação para todos os assinantes. No entanto, para confirmar a transação, você deve inserir um comando Complete-Transaction 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 cmdlet Get-Transaction 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 parâmetro Independent do cmdlet Start-Transaction.
Quando você inicia uma transação independente, Start-Transaction 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.
Tenha isso em mente 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 de registro, digite "get-help registry".
EXEMPLO 1: CONFIRMANDO UMA TRANSAÇÃO
Para criar uma transação, use o cmdlet Start-Transaction. 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 unidade HKCU:, 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 cmdlet New-Item 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 cmdlet Complete-Transaction. Como ele sempre afeta a transação ativa, você não pode especificar a transação.
complete-transaction
Como resultado, a chave MyCompany é 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 cmdlet Start-Transaction. 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 cmdlet New-Item 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 cmdlet Undo-Transaction. Como ele sempre afeta a transação ativa, você não especifica a transação.
Undo-transaction
O resultado é que a chave MyOtherCompany 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 eles 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 comando Get-ChildItem (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 cmdlet New-ItemProperty para adicionar a entrada do Registro MyKey à 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 comando Get-ChildItem ("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 à chave MyCompany.
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 comando Get-ChildItem ("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 entrada MyKey será adicionada à chave MyCompany.
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 chave do Registro HKCU:\Software.
start-transaction
Os próximos três comandos usam o cmdlet New-Item 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 comando Get-ChildItem ("dir") sem o parâmetro UseTransaction. Esse comando obtém itens que começam com "M".
dir m*
O resultado mostra que a chave MyCompany2 é adicionada ao registro, mas as chaves MyCompany1 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 é projetado para scripts que executam transações. Normalmente, os scripts 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 chave do Registro HKCU:\Software.
start-transaction
O comando a seguir usa o cmdlet New-Item para adicionar a chave MyCompany 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 chave MyCompany 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 comando Get-Transaction 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 desejar que a transação seja mais tolerante a erros, você 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 "Nunca".
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 CMDLET USE-TRANSACTION
O cmdlet Use-Transaction 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 do .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 New-Object a seguir cria uma instância da classe TransactedString e a salva na variável $t.
$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 método ToString 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, incorpore a expressão em um comando Use-Transaction.
use-transaction {$s.tostring()} -usetx
A saída mostra a exibição da transação.
PowerShell
O comando a seguir confirma a transação.
complete-transaction
Para ver a cadeia de caracteres 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 chave HKCU:\Software.
start-transaction
O comando a seguir usa o comando Get-Transaction 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 comando Start-Transaction para iniciar uma transação. Embora esse comando seja digitado no prompt de comando, esse cenário é mais provável de acontecer quando você executa um script que contém uma transação.
start-transaction
Um comando Get-Transaction 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 cmdlet New-ItemProperty 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 comando Get-Transaction mostra que a contagem de assinantes no objeto de transação é 1, mas o valor de Status ainda está 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 comando Complete-Transaction para cada comando Start-Transaction.
complete-transaction
Outro comando Get-Transaction 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 de Start-Transaction para tornar a nova transação independente da transação original.
Quando você fizer isso, Start-Transaction cria um novo objeto de transação e torna a nova transação a transação ativa.
Comece iniciando uma transação na chave HKCU:\Software.
start-transaction
O comando a seguir usa o comando Get-Transaction 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 comando Get-Transaction 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, reverter a transação mais recente cancela as alterações do Registro e torna a transação original a transação ativa.
undo-transaction
Um comando Get-Transaction 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 comando Get-ChildItem mostra que o registro foi alterado.
dir m*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
83 1 Microsoft {(default)}
0 0 MyCompany {}
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de