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

	




Sumário