TÓPICO
about_Transactions
DESCRIÇÃO RESUMIDA
Descreve como gerenciar operações transacionadas no Windows
PowerShell.
DESCRIÇÃO LONGA
O Windows PowerShell tem suporte para transações desde o Windows
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 TRANSAÇÕES
No Windows 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 por ela. Ou então pode ser completamente desfeita
("revertida"), de forma que os dados afetados não sejam alterados por ela.
Como os comandos em uma transação são gerenciados como uma
unidade, todos os comandos são confirmados ou revertidos.
As transações são amplamente utilizadas em processamento de dados,
especialmente em operações de banco de dados e para transações
financeiras. Geralmente, as transações são usadas quando o pior
cenário possível para um conjunto de comandos não é a falha de todos,
mas o êxito de alguns e a falha de outros, deixando o sistema em um estado danificado,
falso ou sem interpretação que é difícil de reparar.
CMDLETS DE TRANSAÇÃO
O Windows PowerShell inclui vários cmdlets projetados para gerenciar
transações.
Cmdlet Descrição
-------------- ---------------------------------
Start-Transaction Inicia uma nova transação.
Use-Transaction Adiciona um comando ou uma
expressão à transação. O comando deve
usar objetos habilitados para transações.
Undo-Transaction Reverte a transação, de forma
que nenhum dado seja alterado por ela.
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 <nome-do-cmdlet> -detailed
Por exemplo:
get-help use-transaction -detailed
ELEMENTOS HABILITADOS PARA TRANSAÇÕES
Para participar de uma transação, o cmdlet e o provedor devem
dar suporte a transações. Esse recurso é interno aos objetos
afetados pela transação.
O provedor Registry do Windows PowerShell dá suporte para
transações no Windows Vista. O objeto TransactedString
(Microsoft.PowerShell.Commands.Management.TransactedString) funciona
com qualquer sistema operacional que execute o Windows PowerShell.
Outros provedores do Windows PowerShell podem dar suporte para
transações. Para localizar os provedores do Windows PowerShell
na sua sessão que dão suporte para transações, use o comando a
seguir para encontrar o valor "Transactions" 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 a Ajuda do provedor, digite:
get-help <nome_do_provedor>
Por exemplo, para obter Ajuda para o provedor Registry, digite:
get-help registry
O PARÂMETRO USETRANSACTION
Os cmdlets com suporte para 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 só poderá ser usado quando a sessão contiver 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 Windows PowerShell, todos os cmdlets projetados
para funcionar com provedores do Windows PowerShell dão suporte para
transações. Como resultado, você pode usar os cmdlets de provedores
para gerenciar transações.
Para obter mais informações sobre os provedores do Windows
PowerShell, consulte about_Providers.
O OBJETO DE TRANSAÇÃO
As transações são representadas no Windows 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 quando usar Start-Transaction para iniciar a
transação.
A preferência de reversão determina as condições nas 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, Committed e RolledBack.
SubscriberCount:
Contém o número de assinantes da transação. Um assinante é
adicionado à transação quando você a inicia enquanto há
outra transação em andamento. A contagem de assinantes
diminui quando um assinante confirma a transação.
TRANSAÇÕES ATIVAS
No Windows PowerShell, só uma transação fica ativa de cada vez,
e você pode gerenciar somente a transação ativa. Várias
transações podem estar em andamento ao mesmo tempo na mesma
sessão, mas só a transação iniciada mais recentemente estará ativa.
Como resultado, você não pode definir uma transação específica
ao utilizar os cmdlets de transação. Os comandos sempre se aplicam à
transação ativa.
Isso fica mais evidente no comportamento do cmdlet
Get-Transaction. Quando você insere um comando Get-Transaction, Get-
Transaction sempre obtém somente um objeto de transação. Esse objeto
é o que representa a transação ativa.
Para gerenciar outra transação, 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 se tornam ativas na ordem
inversa àquela em que são iniciadas, de forma que a transação
iniciada mais recentemente seja sempre a ativa.
ASSINANTES E TRANSAÇÕES INDEPENDENTES
Se você iniciar uma transação enquanto outra estiver em
andamento, por padrão, o Windows PowerShell não iniciará uma
nova transação. Em vez disso, ele adicionará um "assinante" à
transação atual.
Quando uma transação tem vários assinantes, um único comando Undo-
Transaction pode, em qualquer ponto, reverter toda a transação para
todos os assinantes. No entanto, para confirmar a transação, você
precisa inserir um comando Complete-Transaction para cada assinante.
Para determinar o número de assinantes de uma transação, consulte 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
A adição de um assinante é o comportamento padrão, pois a
maioria das transações iniciadas enquanto há outra em andamento se
relacionam à 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. Por serem relacionadas, as transações 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 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ê a confirme.
Contudo, os mesmos dados podem ser alterados por comandos que
não fazem parte da transação.
Lembre-se disso quando usar transações para gerenciar dados
compartilhados. Normalmente, os bancos de dados têm mecanismos
que bloqueiam os dados enquanto você trabalha neles, impedindo
outros usuários, e também outros comandos, scripts e funções,
de alterá-los.
Contudo, o bloqueio é um recurso do banco de dados. Não se
relaciona às transações. Se você estiver trabalhando em um
sistema de arquivos ou outro repositório de dados habilitado
para transações, os dados poderão ser alterados com a transação
em andamento.
EXEMPLOS
Os exemplos nesta seção usam o provedor Registry do Windows
PowerShell e pressupõem que você esteja familiarizado com ele.
Para obter informações sobre o provedor Registry, 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, não são incluídos comandos
na transação.
Por exemplo, o comando a seguir, que define o local atual na
chave Software da unidade HKCU:, não é 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 não é 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 1 MyCompany {}
EXEMPLO 2: REVERTENDO 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 não é 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
Como resultado, 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 dados.
Contudo, os comandos que obtêm dados também são úteis em uma
transação, pois obtêm dados dentro da transação. Isso fornece uma
visualização das alterações que seriam causadas pela confirmação
da transação.
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 de 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 de
Registro, mas a entrada de Registro não é alterada.
MyKey
-----
123
Para obter os itens 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 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 exibe os dados internos à 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 de Registro
HKCU:\Software.
start-transaction
Os três próximos 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, 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. Este
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.
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. Normalmente, os scripts são bem testados e incluem
lógica de manipulação de erros; assim, os erros não são esperados
e devem encerrar a transação.
O primeiro comando inicia uma transação na chave de 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 : Já existe uma chave neste caminho
At line:1 char:9
+ new-item <<<< MyCompany -usetx
Um comando Get-Transaction confirma que a transação foi revertida
e que SubscriberCount é 0.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 0 RolledBack
EXEMPLO 6: ALTERANDO A PREFERÊNCIA DE REVERSÃO
Se você quiser que a transação tenha mais tolerância 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 preferência de
reversão "Never".
start-transaction -rollbackpreference Never
Nesse caso, quando o comando falha, a transação não é revertida
automaticamente.
New-Item MyCompany -UseTX
New-Item : Já existe uma chave neste caminho
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 direcionar scripts para objetos do
Microsoft .NET Framework habilitados para transações.
Use-Transaction tem um bloco de script que só pode conter comandos e
expressões que usam objetos do .NET Framework habilitados para
transações, 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.Tran
sactedString
O comando a seguir usa o método Append do objeto TransactedString para
adicionar texto à cadeia de caracteres. Como esse 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 o adiciona como parte da transação. O comando é
colocado entre chaves, e é definido como valor do parâmetro
ScriptBlock de Use-Transaction. O parâmetro UseTransaction (UseTx) é
obrigató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 somente as alterações não transacionadas estão
em vigor.
Windows
Para ver o conteúdo atual da cadeia de caracteres transacionada
em $t a partir da transação, incorpore a expressão em um comando Use-
Transaction.
use-transaction {$s.tostring()} -usetx
A saída traz a exibição da transação.
Windows PowerShell
O comando a seguir confirma a transação.
complete-transaction
Para ver a cadeia de caracteres final:
$t.tostring()
Windows PowerShell
EXEMPLO 8: GERENCIANDO TRANSAÇÕES COM VÁRIOS ASSINANTES
Quando você inicia uma transação enquanto há outra em andamento,
por padrão, o Windows PowerShell não cria uma segunda transação.
Em vez disso, ele adiciona um assinante à transação atual.
Este exemplo mostra como exibir e gerenciar uma transação com vários
assinantes.
Comece iniciando uma transação na chave HKCU:\Software.
start-transaction
O comando a seguir usa o cmdlet 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 o comando seja digitado no prompt de
comando, é mais provável que esse cenário ocorra quando você
executar um script que contenha uma transação.
start-transaction
Um comando Get-Transaction mostra que a contagem de assinantes no
objeto de transação aumentou. O valor agora é 2.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 Active
O comando a seguir usa o cmdlet New-ItemProperty para adicionar a
entrada de 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 o 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 reversão ocorreria 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 é Active (e não
Committed).
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
Para concluir a confirmação da transação, digite um segundo
comando Complete-Transaction. Para confirmar uma transação com vários
assinantes, você precisa 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
Quando você inicia uma transação enquanto há outra em andamento,
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 criará um novo objeto
de transação, e a nova transação se tornará a transação ativa.
Comece iniciando uma transação na chave HKCU:\Software.
start-transaction
O comando a seguir usa o cmdlet 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 de Registro MyCompany como
parte da nova 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 a transação não é 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 a SubscriberCount da transação é 1, indicando que não
há nenhum outro assinante e que a transação é nova.
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
A nova transação deve primeiro ser concluída (confirmada ou
revertida) para 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, sua reversão reverteria toda a transação para todos os
assinantes.
Porém, como essas transações são independentes, reverter a mais
nova cancela as alterações no Registro e torna ativa a transação
original.
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 {}
CONSULTE TAMBÉM
Start-Transaction
Get-Transaction
Complete-Transaction
Undo-Transaction
Use-Transaction
Registry (provedor)
about_Providers
Get-PSProvider
Get-ChildItem