Compartir a través de

Start-Transaction

  • Referencia
Módulo:
Microsoft.PowerShell.Management

Inicia una transacción.

Sintaxis

Start-Transaction
     [-Timeout <Int32>]
     [-Independent]
     [-RollbackPreference <RollbackSeverity>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Description

El Start-Transaction cmdlet inicia una transacción, que es una serie de comandos que se administran como una unidad. Se puede completar una transacción o confirmarse. Como alternativa, puede deshacerse por completo o revertirse, de modo que los datos modificados por la transacción se restauren a su estado original. Como los comandos en una transacción se administran como una unidad, se confirman o se revierten todos los comandos.

De forma predeterminada, si algún comando de la transacción genera un error, las transacciones se revierten automáticamente. Puede usar el parámetro RollbackPreference para cambiar este comportamiento.

Los cmdlets usados en una transacción se deben diseñar para que admitan transacciones. Los cmdlets que admiten transacciones tienen un parámetro UseTransaction . Para realizar las transacciones de un proveedor, el proveedor debe admitir transacciones. El proveedor del Registro de Windows PowerShell en Windows Vista y versiones posteriores del sistema operativo Windows admite transacciones. También puede usar la clase Microsoft.PowerShell.Commands.Management.TransactedString para incluir expresiones en transacciones en cualquier versión del sistema Windows que admita Windows PowerShell. Otros proveedores de Windows PowerShell también pueden admitir transacciones.

Solo puede haber activa una transacción a la vez. Si inicia una transacción nueva e independiente mientras una transacción está en curso, la nueva transacción se convierte en la transacción activa y debe confirmar o revertir la nueva transacción antes de realizar cambios en la transacción original.

Start-Transaction cmdlet es uno de un conjunto de cmdlets que admiten la característica de transacciones en Windows PowerShell. Para obtener más información, consulte about_Transactions.

Ejemplos

Ejemplo 1: Iniciar y revertir una transacción

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Undo-Transaction

Estos comandos inician y después revierten una transacción. Dado que la transacción se revierte, no se realizan cambios en el Registro.

Ejemplo 2: Iniciar y completar una transacción

Set-Location hkcu:\software
Start-Transaction
New-Item "ContosoCompany" -UseTransaction
New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
Complete-Transaction

Estos comandos inician y después completan una transacción. No se realizan cambios en el Registro hasta que se use el Complete-Transaction comando .

Ejemplo 3: Usar diferentes preferencias de reversión

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

# Succeeds

En este ejemplo se muestra el efecto de cambiar el valor del parámetro RollbackPreference .

En el primer conjunto de comandos, Start-Transaction no usa RollbackPreference. Como resultado, se usa el valor predeterminado (Error). Cuando se produce un error en un comando de transacción, es decir, la ruta de acceso especificada no existe, la transacción se revierte automáticamente.

En el segundo conjunto de comandos, Start-Transaction usa RollbackPreference con un valor de Never. Como resultado, cuando se produce un error en un comando de transacción, la transacción todavía está activa y se puede completar correctamente.

Dado que la mayoría de las transacciones deben realizarse sin errores, normalmente se prefiere el valor predeterminado de RollbackPreference .

Ejemplo 4: Uso de este cmdlet mientras una transacción está en curso

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                 Active

En este ejemplo se muestra el efecto de usar Start-Transaction mientras una transacción está en curso. El efecto es muy similar al de unirse a la transacción en curso.

Aunque se trata de un comando simplificado, este escenario se produce con frecuencia cuando la transacción implica ejecutar un script que incluye una transacción completa.

El primer Start-Transaction comando inicia la transacción. El primer New-Item comando forma parte de la transacción.

El segundo Start-Transaction comando agrega un nuevo suscriptor a la transacción. El Get-Transaction comando ahora devuelve una transacción con un recuento de suscriptores de 2. El segundo New-Item comando forma parte de la misma transacción.

No se realizan cambios en el Registro hasta que se complete toda la transacción. Para completar la transacción, debe escribir dos Complete-Transaction comandos, uno para cada suscriptor. Si fuera a revertir la transacción en cualquier momento, toda la transacción se revertiría para ambos suscriptores.

Ejemplo 5: Iniciar una transacción independiente mientras una está en curso

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}

En este ejemplo se muestra el efecto de usar 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 lógicamente independientes, porque solo puede haber una transacción activa a la vez, 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 New-Item comando forma parte de la primera transacción.

En el segundo conjunto de comandos, el Start-Transaction comando usa el parámetro Independent . El Get-Transaction comando siguiente muestra el objeto de transacción para la transacción activa, que es la más reciente. El número de suscriptores es igual a 1, que muestra que las transacciones no están relacionadas.

Cuando la transacción activa se revierte mediante un Undo-Transaction comando , la transacción original vuelve a estar activa.

El New-ItemProperty comando, que forma parte de la transacción original, finaliza sin error y la transacción original se puede completar mediante el Complete-Transaction comando . Como resultado, se cambia el Registro.

Ejemplo 6: Ejecutar comandos que no forman parte de una transacción

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                     {}

En este ejemplo se muestra que los comandos que se envían mientras hay una transacción en curso se pueden incluir o no en la transacción. Solo los comandos que usan el parámetro UseTransaction forman parte de la transacción.

Los comandos primero y tercer New-Item usan el parámetro UseTransaction . Estos comandos forman parte de la transacción. Dado que el segundo New-Item comando no usa el parámetro UseTransaction , no forma parte de la transacción.

El primer comando Get-ChildItem muestra el efecto. El segundo New-Item comando se completa inmediatamente, pero los comandos primero y tercero New-Item no son efectivos hasta que se confirme la transacción.

El Complete-Transaction comando confirma la transacción. Como resultado, el segundo comando Get-ChildItem muestra que todos los elementos nuevos se agregan al registro.

Ejemplo 7: Revertir una transacción que no finaliza en un tiempo 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 -UseTransaction

Este comando usa el parámetro Timeout de Start-Transaction para iniciar una transacción que debe completarse en dos minutos. Si la transacción no finaliza cuando expira el tiempo de espera, se revierte automáticamente.

Cuando expire el tiempo de espera, no se le notificará, pero la propiedad Status del objeto de transacción se establece en RolledBack y los comandos que usan el parámetro UseTransaction producen un error.

Parámetros

-Confirm

Le solicita su confirmación antes de ejecutar el cmdlet.

Tipo:SwitchParameter
Alias:cf
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Independent

Indica que este cmdlet inicia una transacción que es independiente de las transacciones en curso. De forma predeterminada, si usa Start-Transaction mientras otra transacción está en curso, se agrega un nuevo suscriptor a la transacción en curso. Este parámetro tiene efecto solo cuando ya hay una transacción en curso en la sesión.

De forma predeterminada, si usa Start-Transaction mientras una transacción está en curso, se reutiliza el objeto de transacción existente y se incrementa el número de suscriptores. El efecto es muy similar al de unirse a la transacción original. Un Undo-Transaction comando revierte toda la transacción. Para completar la transacción, debe escribir un Complete-Transaction comando para cada suscriptor. Dado que la mayoría de las transacciones que están en curso al mismo tiempo están relacionadas, el valor predeterminado es suficiente para la mayoría de los casos.

Si especifica el parámetro Independent , este cmdlet crea una nueva transacción que se puede completar o deshacer sin afectar a la transacción original. Sin embargo, como solo puede haber una transacción activa a la vez, debe completar o revertir la nueva transacción antes de reanudar el trabajo en la transacción original.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-RollbackPreference

Especifica las condiciones en las que una transacción se revierte automáticamente. Los valores permitidos para este parámetro son los siguientes:

  • Error La transacción se revierte automáticamente si se produce un error de terminación o no terminación.
  • TerminatingError La transacción se revierte automáticamente si se produce un error de terminación.
  • Never La transacción nunca se revierte automáticamente.

El valor predeterminado es Error.

Tipo:RollbackSeverity
Valores aceptados:Error, TerminatingError, Never
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Timeout

Especifica el tiempo máximo, en minutos, que la transacción está activa. Cuando expira el tiempo de espera, la transacción se revierte automáticamente.

De forma predeterminada, no hay ningún 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 de 30 minutos.

Tipo:Int32
Alias:TimeoutMins
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-WhatIf

Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.

Tipo:SwitchParameter
Alias:wi
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Entradas

None

No se puede canalizar la entrada a este cmdlet.

Salidas

None

Este cmdlet no genera ningún resultado.