Inicia una transacción.
Sintaxis
Start-Transaction [-Independent] [-RollbackPreference {<Error> | <TerminatingError> | <Never>}] [-Timeout <int>] [-Confirm] [-WhatIf] [<CommonParameters>]
Descripción
El cmdlet Start-Transaction inicia una transacción, que es una serie de comandos que se administran como una unidad. Una transacción se puede completar ("confirmar") o se puede deshacer ("revertir") totalmente, para que los datos cambiados por la transacción se restauren a su estado original. Dado que los comandos de una transacción se administran como una unidad, o todos se confirman o todos se revierten.
De forma predeterminada, las transacciones se revierten automáticamente si cualquier comando de la transacción genera un error, pero se puede utilizar el parámetro RollbackPreference para cambiar este comportamiento.
Los cmdlets utilizados en una transacción deben diseñarse para admitir transacciones. Los cmdlets que admiten transacciones tienen un parámetro UseTransaction. Para realizar transacciones en un proveedor, el proveedor debe admitir transacciones. El proveedor Registry de Windows PowerShell en Windows Vista y versiones posteriores de Windows admite transacciones. También se puede utilizar la clase Microsoft.PowerShell.Commands.Management.TransactedString para incluir expresiones en transacciones en cualquier versión de Windows que admita Windows PowerShell. Otros proveedores de Windows PowerShell también pueden admitir transacciones.
Solo puede haber una transacción activa a la vez. Si se inicia una nueva transacción independiente mientras otra transacción está en curso (ni completada ni revertida), la nueva transacción se convierte en la transacción activa, y dicha transacción se debe confirmar o revertir antes de realizar cambios en la transacción original.
El cmdlet Start-Transaction es uno de un conjunto de cmdlets que admiten la característica de transacciones en Windows PowerShell. Para obtener más información, vea about_Transactions.
Parámetros
-Independent
Inicia una transacción que es independiente de las transacciones en curso. De forma predeterminada, si se utiliza Start-Transaction mientras otra transacción está en curso, se agrega un nuevo suscriptor a la transacción en curso. Este parámetro sólo tiene un efecto cuando una transacción ya está en curso en la sesión.
De forma predeterminada, si se utiliza Start-Transaction mientras una transacción está en curso, el objeto de transacción existente se reutiliza y el recuento de suscriptores se incrementa. El efecto es muy parecido a unir la transacción original. Un comando Undo-Transaction revierte toda la transacción. Para completar la transacción, se debe escribir un comando Complete-Transaction para cada suscriptor. Dado que la mayor parte de las transacciones que están en curso simultáneamente están relacionadas, el valor predeterminado es suficiente para la mayoría de los usos.
Si se utiliza el parámetro Independent, se crea una nueva transacción que se puede completar o revertir sin afectar a la transacción original. Sin embargo, como solo una transacción puede estar activa a la vez, la nueva transacción se debe completar o revertir antes de reanudar el trabajo en la transacción original.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
Reuse the original transaction object. |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-RollbackPreference <RollbackSeverity>
Especifica las condiciones bajo las cuales una transacción se revierte automáticamente. El valor predeterminado es "Error".
Los valores válidos son:
-- Error: la transacción se revierte automáticamente si se produce un error de terminación o de no terminacióin. "Error" es el valor predeterminado.
-- TerminatingError: la transacción se revierte automáticamente si se produce un error que provoca fin.
-- Never: la transacción nunca se revierte automáticamente.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
Error |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-Timeout <int>
Especifica el período de tiempo máximo, en minutos, que la transacción está activa. Cuando el tiempo de espera expira, la transacción se revierte automáticamente.
De forma predeterminada, no hay tiempo de espera para las transacciones que se inician en la línea de comandos. Cuando las transacciones se inician mediante un script, el tiempo de espera predeterminado es 30 minutos.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
No timeout (infinite) |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-Confirm
Solicita confirmación antes de ejecutar el comando.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
|
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-WhatIf
Describe lo que ocurriría si se ejecutara el comando sin ejecutarlo realmente.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
|
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
<CommonParameters>
Este cmdlet admite los parámetros comunes: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer y -OutVariable. Para obtener más información, vea about_Commonparameters.
Entradas y salidas
El tipo de entrada es el tipo de los objetos que se pueden canalizar al cmdlet. El tipo devuelto es el tipo de los objetos que el cmdlet devuelve.
|
Entradas |
Ninguno No puede canalizar entradas a este cmdlet. |
|
Salidas |
Ninguno Este cmdlet no genera resultados. |
Ejemplo 1
C:\PS>cd hkcu:\software PS HKCU:\software> start-transaction PS HKCU:\software> new-item MyCompany -UseTransaction PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction PS HKCU:\software> undo-transaction Descripción ----------- Estos comandos inician una transacción y, a continuación, la revierten. Dado que la transacción se revierte, no se producen cambios en el Registro.
Ejemplo 2
C:\PS>cd hkcu:\software PS HKCU:\software> start-transaction PS HKCU:\software> new-item MyCompany -UseTransaction PS HKCU:\software> new-itemproperty MyCompany -name MyKey -value 123 -UseTransaction PS HKCU:\software> complete-transaction Descripción ----------- Estos comandos inician una transacción y, a continuación, la completan. No se producirán cambios en el Registro hasta que se utilice el comando Complete-Transaction.
Ejemplo 3
C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
# Start-Transaction (-rollbackpreference error)
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item -path NoPath -Name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -path NoPath -Name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -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 MyCompany -UseTransaction
# Start-Transaction (-rollbackpreference never)
PS HKCU:\software> start-transaction -RollbackPreference never
PS HKCU:\software> new-item -path NoPath -name MyCompany -UseTransaction
New-Item : The registry key at the specified path does not exist.
At line:1 char:9
+ new-item <<<< -path NoPath -name MyCompany -UseTransaction
PS HKCU:\software> new-item -path . -name MyCompany -UseTransaction
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany {}
PS HKCU:\Software> complete-transaction
# Succeeds
Descripción
-----------
En este ejemplo se muestra el efecto de cambiar el valor del parámetro RollbackPreference.
En el primer conjunto de comandos, el comando Start-Transaction no utiliza el parámetro RollbackPreference. Como consecuencia, se usa el valor predeterminado ("Error"). Cuando se produce un error en un comando de transacción (la ruta de acceso especificada no existe), la transacción se revierte automáticamente.
En el segundo conjunto de comandos, el comando Start-Transaction utiliza el parámetro RollbackPreference con el valor "Never". Como consecuencia, si se produce un error en un comando de transacción, esta seguirá estando activa y se podrá completar correctamente.
Dado que la mayoría de las transacciones se deben realizar sin error, se suele preferir el valor predeterminado del parámetro RollbackPreference.
Ejemplo 4
C:\PS>cd HKCU:\software PS HKCU:\software> start-transaction PS HKCU:\software> new-item MyCompany -UseTransaction PS HKCU:\software> start-transaction PS HKCU:\software> get-transaction PS HKCU:\software> new-item MyCompany2 -UseTransaction PS HKCU:\software> complete-transaction PS HKCU:\software> complete-transaction PS HKCU:\Software> Get-Transaction RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 2 Active Descripción ----------- En este ejemplo se muestra el efecto de utilizar el comando Start-Transaction mientras una transacción está en curso. El efecto es muy parecido a unir la transacción en curso. Aunque se trata de un comando simplificado, este escenario suele presentarse cuando la transacción implica la ejecución de un script que incluye una transacción completa. El primer comando Start-Transaction inicia la transacción. El primer comando New-Item forma parte de la transacción. El segundo comando Start-Transaction agrega un nuevo suscriptor a la transacción. El comando Get-Transaction devuelve ahora una transacción con un recuento de suscriptores de 2. El segundo comando New-Item forma parte de la misma transacción. No se producirán cambios en el Registro hasta que se complete la transacción. Para completar la transacción, se deben escribir dos comandos Complete-Transaction, uno para cada suscriptor. Si se revirtiera la transacción en cualquier punto, la transacción completa se revertiría para ambos suscriptores.
Ejemplo 5
C:\PS>cd HKCU:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany -UseTransaction
PS HKCU:\software> start-transaction -independent
PS HKCU:\software> get-transaction
PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
PS HKCU:\Software> get-transaction
RollbackPreference SubscriberCount Status
------------------ --------------- ------
Error 1 Active
PS HKCU:\software> undo-transaction
PS HKCU:\software> new-itemproperty -path MyCompany -name MyKey -value 123 -UseTransaction
MyKey
-----
123
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 1 MyCompany {MyKey}
Descripción
-----------
En este ejemplo se muestra el efecto de utilizar el parámetro Independent de Start-Transaction para iniciar una transacción mientras otra transacción está en curso. En este caso, la nueva transacción se revierte sin afectar a la transacción original.
Aunque las transacciones son independientes de forma lógica, porque solo una transacción puede estar activa a la vez, se debe revertir o confirmar la transacción más reciente antes de reanudar el trabajo en la transacción original.
El primer conjunto de comandos inicia una transacción. El comando New-Item forma parte de la primera transacción.
En el segundo conjunto de comandos, el comando Start-Transaction utiliza el parámetro Independent. El comando Get-Transaction que sigue muestra el objeto de transacción para la transacción activa (la más reciente). El recuento de suscriptores es igual a 1, lo que significa que las transacciones no están relacionadas.
Cuando la transacción activa se revierte utilizando un comando Undo-Transaction, la transacción original vuelve a estar activa.
El comando New-ItemProperty, que forma parte de la transacción original, se completa sin error y la transacción original se puede completar utilizando el comando Complete-Transaction. Como consecuencia, el Registro se cambia.
Ejemplo 6
C:\PS>cd hkcu:\software
PS HKCU:\software> start-transaction
PS HKCU:\software> new-item MyCompany1 -UseTransaction
PS HKCU:\software> new-item MyCompany2
PS HKCU:\software> new-item MyCompany3 -UseTransaction
PS HKCU:\software> dir my*
PS HKCU:\software> complete-transaction
PS HKCU:\software> dir my*
PS HKCU:\Software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany2 {}
PS HKCU:\Software> complete-transaction
PS HKCU:\Software> dir my*
Hive: HKEY_CURRENT_USER\Software
SKC VC Name Property
--- -- ---- --------
0 0 MyCompany1 {}
0 0 MyCompany2 {}
0 0 MyCompany3 {}
Descripción
-----------
En este ejemplo se muestra que los comandos que se envían mientras una transacción está en curso pueden incluirse o no en la transacción. Solo los comandos que utilizan el parámetro UseTransaction forman parte de la transacción.
Los comandos New-Item primero y tercero utilizan el parámetro UseTransaction. Estos comandos forman parte de la transacción. Dado que el segundo comando New-Item no utiliza el parámetro UseTransaction, no forma parte de la transacción.
El primer comando "dir" muestra el efecto. El segundo comando New-Item se completa inmediatamente, pero los comandos New-Item no surten efecto hasta que la transacción se confirma.
El comando Complete-Transaction confirma la transacción. Como consecuencia, el segundo comando "dir" muestra que todos los elementos nuevos se agregan al Registro.
Ejemplo 7
C:\PS>start-transaction -timeout 2 # Wait two minutes... C:\PS> get-transaction C:\PS> new-item HKCU:\Software\MyCompany -UseTransaction C:\PS> start-transaction -timeout 2 # Wait two minutes... C:\PS>> get-transaction RollbackPreference SubscriberCount Status ------------------ --------------- ----------- Error 1 RolledBack C:\PS> new-item HKCU:\Software\MyCompany -UseTransaction New-Item : Cannot use transaction. The transaction has been rolled back or has timed out. At line:1 char:9 + new-item <<<< MyCompany -UseTransaction Descripción ----------- Este comando utiliza el parámetro Timeout de Start-Transaction para iniciar una transacción que debe completarse en dos minutos. Si la transacción no se completa al expirar el tiempo de espera, se revierte automáticamente. Cuando el tiempo de espera expira, no se recibe una notificación, pero la propiedad Status del objeto de transacción se establece en RolledBack y se produce un error al ejecutar los comandos que usan el parámetro UseTransaction.
Vea también