Use-Transaction
Adiciona o bloco de script à transação ativa.
Sintaxe
Default (Default)
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 faz parte de um conjunto de cmdlets que oferecem 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 o 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 ela não faz parte da transação, ela 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, assim como 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 não são alterados.
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 invertidos.
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 executado na transação. Insira qualquer bloco de script válido entre chaves ( { } ). Este parâmetro é obrigatório.
Propriedades do parâmetro
| Tipo: | ScriptBlock |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UseTransaction
Inclui o comando na transação ativa. Esse parâmetro só é válido quando uma transação está em andamento. Para obter mais informações, consulte about_Transactions.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | usetx |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
CommonParameters
Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.
Entradas
None
Não é possível redirecionar a entrada para este cmdlet.
Saídas
PSObject
Esse cmdlet retorna o resultado da transação.
Observações
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 qualquer comando Use-Transaction eficaz.