Share via

Use-Transaction

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

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

Syntax

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

Description

O Use-Transaction cmdlet 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

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

Hello

Use-Transaction -TransactedScript { $transactedString.ToString() } -UseTransaction

Hello, World

Complete-Transaction
$transactedString.ToString()

Hello, World

Este exemplo mostra como usar Use-Transaction para criar scripts em um objeto .NET Framework habilitado para transações. Nesse caso, o objeto é um objeto TransactedString .

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

O segundo comando usa o comando New-Object para criar um objeto TransactedString . Ele armazena o $TransactedString objeto na variável.

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 é usado 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 de 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 Complete-Transaction cmdlet 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

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

Hello

Este exemplo mostra o efeito de reverter uma transação que inclui Use-Transaction comandos. 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 é usado Start-Transaction para iniciar uma transação.

O segundo comando usa New-Object para criar um objeto TransactedString . Ele armazena o $TransactedString objeto na variável.

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 como uma cadeia de $TransactedString 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 incluído em chaves ({}). Este parâmetro é obrigatório.

Type:ScriptBlock
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Aliases:usetx
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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 Use-Transaction cmdlet é sempre usado em transações, esse parâmetro é necessário para tornar qualquer Use-Transaction comando eficaz.