Start-Transaction
Inicia uma transação.
Syntax
Start-Transaction
[-Timeout <Int32>]
[-Independent]
[-RollbackPreference <RollbackSeverity>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Description
O Start-Transaction cmdlet inicia uma transação, que é uma série de comandos gerenciados como uma unidade. Uma transação pode ser concluída ou confirmada. Como alternativa, ele pode ser completamente desfeito ou revertido, para que todos os dados alterados pela transação sejam restaurados ao seu estado original.
Como os comandos em uma transação são gerenciados como uma unidade, todos os comandos são confirmados ou então revertidos.
Por padrão, se qualquer comando na transação gerar um erro, as transações serão revertidas automaticamente. Você pode usar o parâmetro RollbackPreference para alterar esse comportamento.
Os cmdlets usados em uma transação devem ser criados para oferecer suporte a transações. Os cmdlets que oferecem suporte a transações têm um parâmetro UseTransaction . Para realizar transações em um provedor, este provedor deve oferecer suporte a transações. O provedor do Registro do Windows PowerShell no Windows Vista e em versões posteriores do sistema operacional Windows oferece suporte a transações. Você também pode usar a classe Microsoft.PowerShell.Commands.Management.TransactedString para incluir expressões em transações em qualquer versão do sistema Windows que ofereça suporte ao Windows PowerShell. Outros provedores do Windows PowerShell também podem oferecer suporte a transações.
Somente uma transação pode estar ativa por vez. Se você iniciar uma nova transação independente enquanto uma transação estiver em andamento, a nova transação se tornará a transação ativa e você deverá confirmar ou reverter a nova transação antes de fazer qualquer alteração na transação original.
Start-Transaction cmdlet 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: Iniciar e reverter uma transação
Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Undo-TransactionEstes comandos iniciam uma transação e em seguida a revertem. Como a transação é revertida, nenhuma alteração é feita ao registro.
Exemplo 2: Iniciar e concluir uma transação
Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-TransactionEstes comandos iniciam uma transação e em seguida a concluem. Nenhuma alteração é feita no registro até que o Complete-Transaction comando seja usado.
Exemplo 3: Usar preferências de reversão diferentes
Set-Location HKCU:\software
Start-Transaction
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction
Start-Transaction -RollbackPreference never
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction
# Start-Transaction (-rollbackpreference error)
Start-Transaction
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -Path NoPath -Name ContosoCompany -UseTransaction
New-Item -Path . -Name "Contoso" -UseTransaction
New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
At line:1 char:9
+ New-Item <<<< -Path . -Name ContosoCompany -UseTransaction
# Start-Transaction (-rollbackpreference never)
Start-Transaction -RollbackPreference never
New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ New-Item <<<< -Path NoPath -Name "ContosoCompany" -UseTransaction
New-Item -Path . -Name "ContosoCompany" -UseTransaction
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 ContosoCompany {}
Complete-Transaction
# SucceedsEste exemplo demonstra o efeito de alterar o valor do parâmetro RollbackPreference .
No primeiro conjunto de comandos, Start-Transaction não usa RollbackPreference. Como resultado, o valor padrão (Erro) é usado. Quando ocorre um erro em um comando de transação, ou seja, o caminho especificado não existe, a transação é revertida automaticamente.
No segundo conjunto de comandos, Start-Transaction usa RollbackPreference com um valor de Never. Como resultado, quando ocorre um erro em um comando de transação, a transação ainda está ativa e pode ser concluída com êxito.
Como a maioria das transações deve ser executada sem erros, o valor padrão de RollbackPreference normalmente é preferido.
Exemplo 4: Usar este cmdlet enquanto uma transação estiver em andamento
Set-Location HKCU:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
Start-Transaction
Get-Transaction
New-Item "ContosoCompany2" -UseTransaction
Complete-Transaction
Complete-Transaction
Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 2 ActiveEste exemplo mostra o efeito de usar Start-Transaction enquanto uma transação está em andamento.
O efeito é semelhante ao de uma união à transação em andamento.
Embora esse seja um comando simplificado, esse cenário ocorre com frequência quando a transação envolve a execução de um script que inclui uma transação completa.
O primeiro Start-Transaction comando inicia a transação. O primeiro New-Item comando faz parte da transação.
O segundo Start-Transaction comando adiciona um novo assinante à transação. O Get-Transaction comando agora retorna uma transação com uma contagem de assinantes de 2. O segundo New-Item comando faz parte da mesma transação.
Nenhuma alteração é feita no registro até que toda a transação seja concluída. Para concluir a transação, você deve inserir dois Complete-Transaction comandos, um para cada assinante. Se você revertesse a transação a qualquer momento, toda a transação seria revertida para ambos os assinantes.
Exemplo 5: Iniciar uma transação independente enquanto uma está em andamento
Set-Location HKCU:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
Start-Transaction -Independent
Get-Transaction
Undo-Transaction
New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction
Get-ChildItem contoso*
Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
Undo-Transaction
New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
MyKey
-----
123
Complete-Transaction
Get-ChildItem contoso*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 1 MyCompany {MyKey}Este exemplo mostra o efeito de usar o parâmetro Independent de Start-Transaction para iniciar uma transação enquanto outra transação está em andamento.
Neste caso, a nova transação é revertida sem afetar a transação original.
Apesar de as transações serem logicamente independentes, porque somente uma transação pode ficar ativa por vez, você deve reverter ou confirmar a transação mais recente antes de continuar a trabalhar na transação original.
O primeiro conjunto de comandos inicia uma transação.
O New-Item comando faz parte da primeira transação.
No segundo conjunto de comandos, o Start-Transaction comando usa o parâmetro Independent .
O Get-Transaction comando a seguir mostra o objeto de transação para a transação ativa, que é a mais recente.
A contagem de assinantes é igual a 1, o que mostra que as transações não estão relacionadas.
Quando a transação ativa é revertida usando um Undo-Transaction comando, a transação original torna-se ativa novamente.
O New-ItemProperty comando, que faz parte da transação original, é concluído sem erro e a transação original pode ser concluída usando o Complete-Transaction comando.
Como resultado, o registro é alterado.
Exemplo 6: Executar comandos que não fazem parte de uma transação
Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany1" -UseTransaction
New-Item "ContosoCompany2"
New-Item "ContosoCompany3" -UseTransaction
Get-ChildItem contoso*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 ContosoCompany2 {}
Complete-Transaction
Get-ChildItem contoso*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 ContosoCompany1 {}
0 0 ContosoCompany2 {}
0 0 ContosoCompany3 {}Este exemplo demonstra que comandos enviados enquanto uma transação está em andamento podem ser incluídos na transação ou podem não ser incluídos. Somente os comandos que usam o parâmetro UseTransaction fazem parte da transação.
O primeiro e o terceiro New-Item comandos usam o parâmetro UseTransaction . Estes comandos fazem parte da transação. Como o segundo New-Item comando não usa o parâmetro UseTransaction , ele não faz parte da transação.
O primeiro comando Get-ChildItem mostra o efeito. O segundo New-Item comando é concluído imediatamente, mas o primeiro e o terceiro New-Item comandos não são efetivos até que a transação seja confirmada.
O Complete-Transaction comando confirma a transação. Como resultado, o segundo comando Get-ChildItem mostra que todos os novos itens são adicionados ao registro.
Exemplo 7: Reverter uma transação que não é concluída em um tempo especificado
Start-Transaction -Timeout 2
# Wait two minutes...
Get-Transaction
New-Item HKCU:\Software\ContosoCompany -UseTransaction
Start-Transaction -Timeout 2
# Wait two minutes...
Get-Transaction
RollbackPreference SubscriberCount Status
------------------ --------------- -----------
Error 1 RolledBack
New-Item HKCU:\Software\ContosoCompany -UseTransaction
New-Item : Cannot use transaction. The transaction has been rolled back or has timed out.
At line:1 char:9
+ new-item <<<< MyCompany -UseTransactionEsse comando usa o parâmetro Timeout de Start-Transaction para iniciar uma transação que deve ser concluída em dois minutos. Se a transação não for concluída quando o tempo limite expirar, ela será revertida automaticamente.
Quando o tempo limite expira, você não é notificado, mas a propriedade Status do objeto de transação é definida como RolledBack e os comandos que usam o parâmetro UseTransaction falham.
Parâmetros
-Confirm
Solicita sua confirmação antes de executar o cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Independent
Indica que esse cmdlet inicia uma transação que é independente de quaisquer transações em andamento.
Por padrão, se você usar Start-Transaction enquanto outra transação estiver em andamento, um novo assinante será adicionado à transação em andamento. Este parâmetro tem efeito somente quando já existe uma transação em andamento na sessão.
Por padrão, se você usar Start-Transaction enquanto uma transação estiver em andamento, o objeto de transação existente será reutilizado e a contagem de assinantes será incrementada. O efeito é semelhante ao de uma união à transação original. Um Undo-Transaction comando reverte toda a transação.
Para concluir a transação, você deve inserir um Complete-Transaction comando para cada assinante.
Como a maioria das transações que estão em andamento simultaneamente são relacionadas, o padrão é suficiente para a maior parte dos usos.
Se você especificar o parâmetro Independent , esse cmdlet criará uma nova transação que poderá ser concluída ou desfeita sem afetar a transação original. No entanto, como somente uma transação pode estar ativa por vez, você deve concluir ou reverter a nova transação antes de continuar a trabalhar com a transação original.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RollbackPreference
Especifica as condições sob as quais uma transação é revertida automaticamente. Os valores aceitáveis para esse parâmetro são:
ErrorA transação é revertida automaticamente se ocorrer um erro de encerramento ou não.TerminatingErrorA transação é revertida automaticamente se ocorrer um erro de encerramento.NeverA transação nunca é revertida automaticamente.
O valor padrão é Error.
| Type: | RollbackSeverity |
| Accepted values: | Error, TerminatingError, Never |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Timeout
Especifica o tempo máximo, em minutos, pelo qual a transação fica ativa. Quando o tempo limite expira, a transação é revertida automaticamente.
Por padrão, não há tempo limite para transações iniciadas pela linha de comando. Quando as transações são iniciadas por um script, o tempo limite padrão é de 30 minutos.
| Type: | Int32 |
| Aliases: | TimeoutMins |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
None
Não é possível redirecionar a entrada para este cmdlet.
Saídas
None
Este cmdlet não gera saída.
Links Relacionados
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de