Start-Transaction

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

El cmdlet Start-Transaction 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. Dado que los comandos de una transacción se administran como una unidad, todos los comandos se confirman o todos los comandos se revierten.

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 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 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 una transacción puede estar activa 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.

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

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Undo-Transaction

Estos comandos inician y, a continuación, revierten una transacción. Dado que la transacción se revierte, no se realizan cambios en el registro.

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> New-ItemProperty "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Complete-Transaction

Estos comandos inician y, a continuación, completan una transacción. No se realizan cambios en el registro hasta que se use el comando complete-Transaction .

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction -RollbackPreference never
PS HKCU:\software> New-Item -Path "NoPath" -Name "ContosoCompany" -UseTransaction
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction

# Start-Transaction (-rollbackpreference error)

PS HKCU:\software> Start-Transaction
PS HKCU:\software> 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

PS HKCU:\software> 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)

PS HKCU:\software> Start-Transaction -RollbackPreference never
PS HKCU:\software> 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
PS HKCU:\software> New-Item -Path . -Name "ContosoCompany" -UseTransaction

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany                 {}
PS HKCU:\Software> 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 sigue 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.

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction
PS HKCU:\software> Get-Transaction
PS HKCU:\software> New-Item "ContosoCompany2" -UseTransaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\Software> 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 parecido a unir 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 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 ahora devuelve una transacción con un número de suscriptores de 2. El segundo comando New-Item 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 comandos Complete-Transaction, uno para cada suscriptor. Si fuera a revertir la transacción en cualquier momento, toda la transacción se revertiría para ambos suscriptores.

PS C:\> cd HKCU:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany" -UseTransaction
PS HKCU:\software> Start-Transaction -Independent
PS HKCU:\software> Get-Transaction
PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
PS HKCU:\Software> Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   ------
Error                1                 Active
PS HKCU:\software> Undo-Transaction
PS HKCU:\software> New-ItemProperty -Path "ContosoCompany" -Name "MyKey" -Value 123 -UseTransaction
MyKey
-----
123
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir 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 una transacción puede estar 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 comando New-Item forma parte de la primera transacción.

En el segundo conjunto de comandos, el comando Start-Transaction usa el parámetro Independent. El comando Get-Transaction que sigue 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 comando Deshacer transacción, la transacción original vuelve a activarse.

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

PS C:\> cd hkcu:\software
PS HKCU:\software> Start-Transaction
PS HKCU:\software> New-Item "ContosoCompany1" -UseTransaction
PS HKCU:\software> New-Item "ContosoCompany2"
PS HKCU:\software> New-Item "ContosoCompany3" -UseTransaction
PS HKCU:\software> dir contoso*
PS HKCU:\software> Complete-Transaction
PS HKCU:\software> dir contoso*
PS HKCU:\Software> dir contoso*

Hive: HKEY_CURRENT_USER\Software
SKC  VC Name                           Property
---  -- ----                           --------
0   0 ContosoCompany2                {}

PS HKCU:\Software> Complete-Transaction
PS HKCU:\Software> dir 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 una transacción está en curso se pueden incluir en la transacción o no se incluyen. Solo los comandos que usan el parámetro UseTransaction forman parte de la transacción.

El primer y el tercer comandos new-item usan el parámetro UseTransaction . Estos comandos forman parte de la transacción. Dado que el segundo comando New-Item no usa 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 el primero y el tercero comandos new-Item no son efectivos hasta que se confirme la transacción.

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

PS C:\> Start-Transaction -Timeout 2

# Wait two minutes...

PS C:\> Get-Transaction
PS C:\> New-Item HKCU:\Software\ContosoCompany -UseTransaction
PS C:\> Start-Transaction -Timeout 2

# Wait two minutes...

PS C:\> > Get-Transaction

RollbackPreference   SubscriberCount   Status
------------------   ---------------   -----------
Error                1                 RolledBack

PS C:\> 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.

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

No se puede canalizar la entrada a este cmdlet.

Este cmdlet no genera ningún resultado.