Partilhar via

Use-Transaction

  • Referência
Módulo:
Microsoft.PowerShell.Management

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

Sintaxe

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

Description

O cmdlet Use-Transaction adiciona um bloco de script a uma transação ativa. Isso permite que você faça scripts transacionados usando objetos do Microsoft .NET Framework habilitados para transações. O bloco de script pode conter somente objetos do .NET Framework habilitados para transação, como instâncias da classe Microsoft.PowerShell.Commands.Management.TransactedString.

O parâmetro UseTransaction, que é opcional para a maioria dos cmdlets, é necessário quando você usa esse cmdlet.

Use-Transaction é um 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.

Exemplos

Exemplo 1: Script usando um objeto habilitado para transação

PS C:\> Start-Transaction
PS C:\> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
PS C:\> $transactedString.Append("Hello")
PS C:\> Use-Transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
PS C:\> $transactedString.ToString()
Hello
PS C:\> Use-Transaction -TransactedScript { $transactedString.ToString() } -UseTransaction
Hello, World
PS C:\> Complete-Transaction
PS C:\> $transactedString.ToString()
Hello, World

Este exemplo mostra como usar Use-Transaction para criar scripts em um objeto .NET Framework habilitado para transação. Nesse caso, o objeto é um 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 faz parte da transação. O outro comando não é.

O terceiro comando usa o método Append da cadeia de caracteres transacionada para adicionar Hello ao valor de $TransactedString. Como o comando não faz parte da transação, a alteração é aplicada imediatamente.

O quarto comando usa Use-Transaction para adicionar texto à cadeia de caracteres na 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 é necessário neste comando.

O quinto e sexto comandos usam o método ToString do objeto TransactedString para exibir o valor do TransactedString como uma cadeia de caracteres. Novamente, um comando faz parte da transação. A outra transação não é.

O quinto comando usa o método ToString para exibir o valor atual da variável $TransactedString. Como não faz parte da transação, ele exibe apenas o estado atual da cadeia de caracteres.

O sexto comando usa Use-Transaction para executar o mesmo comando na transação. Como o comando faz parte da transação, ele exibe o valor atual da cadeia de caracteres na transação, da mesma forma que 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: reverter uma transação

PS C:\> Start-Transaction
PS C:\> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString
PS C:\> $transactedString.Append("Hello")
PS C:\> Use-Transaction -TransactedScript { $transactedString.Append(", World") } -UseTransaction
PS C:\> Undo-Transaction
PS C:\> $transactedString.ToString()
Hello

Este exemplo mostra o efeito de reverter uma transação que inclui comandos Use-Transaction. Como todos os comandos em uma transação, quando a transação é revertida, as alterações transacionadas são descartadas e os dados permanecem inalterados.

O primeiro comando usa Start-Transaction para iniciar uma transação.

O segundo comando usa 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 Use-Transaction para executar outro comando que usa o método Append na 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 de $TransactedString como uma cadeia de caracteres. Os resultados mostram que apenas as alterações feitas fora da transação foram aplicadas ao objeto.

Parâmetros

-TransactedScript

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

Tipo:ScriptBlock
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-UseTransaction

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

Tipo:SwitchParameter
Aliases:usetx
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

Não é possível canalizar a entrada para este cmdlet.

Saídas

PSObject

Este cmdlet retorna o resultado da transação.

Notas

  • O parâmetro UseTransaction inclui o comando na transação ativa. Como o cmdlet Use-Transaction é sempre usado em transações, esse parâmetro é necessário para tornar efetivo qualquer comando Use-Transaction.