Use-Transaction

Artigo
10/30/2009

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

Nenhum

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 cadeia de caracteres 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 à cadeia de caracteres 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 cadeia de caracteres. 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 cadeia de caracteres.

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 cadeia de caracteres 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 cadeia de caracteres.

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 cadeia de caracteres. O resultado mostra que apenas as alterações feitas fora da transação foram aplicadas ao objeto.

Consulte também

Conceitos

about_Transactions
Start-Transaction
Get-Transaction
Complete-Transaction
Undo-Transaction

Compartilhar via