Use-Transaction

Adiciona o bloco de scripts à transação ativa.

Sintaxe

Use-Transaction [-TransactedScript] <scriptblock> [-UseTransaction] [<CommonParameters>]

Descrição

O cmdlet Use-Transaction adiciona um bloco de scripts à transação ativa. Isso permite que você crie scripts de transações usando objetos Microsoft .NET Framework habilitados por transações. O bloco de script pode conter apenas objetos .NET Framework habilitados por transações, como instâncias da classe Microsoft.PowerShell.Commands.Management.TransactedString.

O parâmetro UseTransaction, que é opcional para a maioria dos cmdlets, é obrigatório quando deste cmdlet é usado.

O cmdlet Use-Transaction faz parte de um conjunto de cmdlets que dão suporte ao recurso de transações no Windows PowerShell. Para obter mais informações, consulte about_Transactions.

Parâmetros

-TransactedScript <scriptblock>

Especifica o bloco de scripts que é executado na transação. Digite qualquer bloco de script válido entre chaves ( { } ). Esse parâmetro é obrigatório.

Necessário? true
Posição? 1
Valor padrão nenhum
Aceitar entrada do pipeline? false
Aceitar caracteres curinga? false

-UseTransaction

Inclui o comando na transação ativa. Este parâmetro é válido apenas quando uma transação está em andamento. Para obter mais informações, consulte about_Transactions.

Necessário? false
Posição? named
Valor padrão
Aceitar entrada do pipeline? false
Aceitar caracteres curinga? false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas None

Você não pode canalizar a entrada para este cmdlet.

Saídas PSObject

Use-Transaction retorna o resultado da transação.

Observações

O parâmetro Use-Transaction inclui o comando na transação ativa. Como o cmdlet Use-Transaction é sempre usado nas transações, esse parâmetro é obrigatório para tornar qualquer comando Use-Transaction efetivo.

Exemplo 1

C:\PS>start-transaction
C:\PS> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
C:\PS> $transactedString.Append("Hello")
C:\PS> use-transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
C:\PS> $transactedString.ToString()
Hello C:\PS> use-transaction -transactedScript { $transactedString.ToString() } -UseTransaction
Hello, World
C:\PS> complete-transaction
C:\PS> $transactedString.ToString()
Hello, World
Descrição
-----------
Esse exemplo mostra como usar o cmdlet Use-Transaction para executar scripts nos objetos .NET Framework habilitados por transações. Nesse caso, o objeto é TransactedString. 
O primeiro comando usa o cmdlet Start-Transaction para iniciar uma transação. 
O segundo comando usa o comando New-Object para criar um objeto TransactedString. Ele armazena o objeto na variável $TransactedString.
O terceiro e o quarto comandos usam o método Append do objeto TransactedString para adicionar texto ao valor de $TransactedString. Um comando é parte da transação, o outro não.
O terceiro comando usa o método Append da string de transações para adicionar "Hello" ao valor de $TransactedString. Como esse comando não faz parte da transação, a alteração é aplicada imediatamente.
O quarto comando usa o cmdlet Use-Transaction para adicionar texto à string dentro da transação. O comando usa o método Append para adicionar ", World" ao valor de $TransactedString. O comando é colocado entre chaves para torná-lo um bloco de script. O parâmetro UseTransaction é obrigatório nesse comando.
O quinto e o sexto comandos usam o método ToString do objeto TransactedString para exibir o valor de TransactedString como uma string. Novamente, um comando faz parte da transação, o outro não.
O quinto comando usa o método ToString para exibir o valor atual da variável $TransactedString. Como ele não faz parte da transação, ele exibe apenas o estado atual da string.
O sexto comando usa o cmdlet Use-Transaction para executar o mesmo comando dentro da transação. Como o comando é parte da transação, ele exibe o valor atual da string dentro da transação, semelhantemente a uma visualização das alterações da transação.
O sétimo comando usa o cmdlet Complete-Transaction para confirmar a transação.
O comando final usa o método ToString para exibir o valor resultante da variável como uma string.

Exemplo 2

C:\PS>start-transaction
C:\PS> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
C:\PS> $transactedString.Append("Hello")
C:\PS> use-transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
C:\PS> undo-transaction
C:\PS> $transactedString.ToString()
Hello
Descrição
-----------
Este exemplo mostra o efeito da reversão de uma transação que inclui comandos Use-Transaction. Como todos os comandos em uma transação, quando esta é revertida, as alterações das transações são descartadas e os dados ficam inalterados.
O primeiro comando usa o cmdlet Start-Transaction para iniciar uma transação. 
O segundo comando usa o comando New-Object para criar um objeto TransactedString. Ele armazena o objeto na variável $TransactedString.
O terceiro comando, que não faz parte da transação, usa o método Append para adicionar "Hello" ao valor de $TransactedString. 
O quarto comando usa o cmdlet Use-Transaction para executar outro comando que usa o método Append dentro da transação. O comando usa o método Append para adicionar ", World" ao valor de $TransactedString. 
O quinto comando usa o cmdlet Undo-Transaction para reverter a transação. Como resultado, todos os comandos executados na transação são revertidos.
O comando final usa o método ToString para exibir o valor resultante da variável $TransactedString como uma string. O resultado mostra que apenas as alterações feitas fora da transação foram aplicadas ao objeto.

See Also