Partager via

Start-Transaction

  • Référence
Module:
Microsoft.PowerShell.Management

Démarre une transaction.

Syntaxe

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

Description

L’applet de commande start-transaction démarre une transaction, qui est une série de commandes gérées en tant qu’unité. Une transaction peut être terminée ou validée. Il peut également être entièrement annulé ou restauré afin que toutes les données modifiées par la transaction soient restaurées à son état d’origine. Étant donné que les commandes d’une transaction sont gérées en tant qu’unité, toutes les commandes sont validées ou toutes les commandes sont restaurées.

Par défaut, si une commande de la transaction génère une erreur, les transactions sont restaurées automatiquement. Vous pouvez utiliser le paramètre RollbackPreference pour modifier ce comportement.

Les applets de commande utilisées dans une transaction doivent être conçues pour prendre en charge les transactions. Les applets de commande qui prennent en charge les transactions ont un paramètre UseTransaction. Pour effectuer des transactions dans un fournisseur, le fournisseur doit prendre en charge les transactions. Le fournisseur de Registre Windows PowerShell dans Windows Vista et les versions ultérieures du système d’exploitation Windows prend en charge les transactions. Vous pouvez également utiliser la classe Microsoft.PowerShell.Commands.Management.TransactedString pour inclure des expressions dans des transactions sur n’importe quelle version du système Windows qui prend en charge Windows PowerShell. D’autres fournisseurs Windows PowerShell peuvent également prendre en charge les transactions.

Une seule transaction peut être active à la fois. Si vous démarrez une nouvelle transaction indépendante pendant qu’une transaction est en cours, la nouvelle transaction devient la transaction active et vous devez valider ou restaurer la nouvelle transaction avant d’apporter des modifications à la transaction d’origine.

applet de commande Start-Transaction est l’un des ensembles d’applets de commande qui prennent en charge la fonctionnalité de transactions dans Windows PowerShell. Pour plus d’informations, consultez about_Transactions.

Exemples

Exemple 1 : Démarrer et restaurer une transaction

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

Ces commandes démarrent, puis restaurent une transaction. Étant donné que la transaction est restaurée, aucune modification n’est apportée au Registre.

Exemple 2 : Démarrer et terminer une transaction

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

Ces commandes démarrent, puis terminent une transaction. Aucune modification n’est apportée au Registre tant que la commande Complete-Transaction n’est pas utilisée.

Exemple 3 : Utiliser différentes préférences de restauration

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

Cet exemple illustre l’effet de la modification de la valeur de paramètre RollbackPreference.

Dans le premier jeu de commandes, start-transaction n’utilise pas rollbackPreference. Par conséquent, la valeur par défaut (Erreur) est utilisée. Lorsqu’une erreur se produit dans une commande de transaction, autrement dit, le chemin spécifié n’existe pas, la transaction est automatiquement restaurée.

Dans le deuxième jeu de commandes, start-transaction utilise RollbackPreference avec la valeur Never. Par conséquent, lorsqu’une erreur se produit dans une commande de transaction, la transaction est toujours active et peut être effectuée avec succès.

Étant donné que la plupart des transactions doivent être effectuées sans erreur, la valeur par défaut de RollbackPreference est généralement préférée.

Exemple 4 : Utiliser cette applet de commande pendant qu’une transaction est en cours

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

Cet exemple montre l’effet de l’utilisation de start-transaction pendant qu’une transaction est en cours. L’effet est beaucoup comme la jointure de la transaction en cours.

Bien qu’il s’agit d’une commande simplifiée, ce scénario se produit fréquemment lorsque la transaction implique l’exécution d’un script qui inclut une transaction complète.

La première commande Start-Transaction démarre la transaction. La première commande New-Item fait partie de la transaction.

La deuxième commande Start-Transaction ajoute un nouvel abonné à la transaction. La commande Get-Transaction retourne maintenant une transaction avec un nombre d’abonnés de 2. La deuxième commande New-Item fait partie de la même transaction.

Aucune modification n’est apportée au Registre tant que l’intégralité de la transaction n’est pas terminée. Pour terminer la transaction, vous devez entrer deux commandes Complete-Transaction, une pour chaque abonné. Si vous deviez restaurer la transaction à tout moment, toutes les transactions seraient restaurées pour les deux abonnés.

Exemple 5 : Démarrer une transaction indépendante alors qu’une transaction est en cours

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}

Cet exemple montre l’effet de l’utilisation du paramètre Independent de start-transaction pour démarrer une transaction pendant qu’une autre transaction est en cours. Dans ce cas, la nouvelle transaction est restaurée sans affecter la transaction d’origine.

Bien que les transactions soient logiquement indépendantes, car une seule transaction peut être active à la fois, vous devez restaurer ou valider la transaction la plus récente avant de reprendre le travail sur la transaction d’origine.

Le premier ensemble de commandes démarre une transaction. La commande New-Item fait partie de la première transaction.

Dans le deuxième jeu de commandes, la commande Start-Transaction utilise le paramètre Independent. La commande Get-Transaction qui suit montre l’objet de transaction pour la transaction active, qui est la plus récente. Le nombre d’abonnés est égal à 1, ce qui indique que les transactions ne sont pas liées.

Lorsque la transaction active est restaurée à l’aide d’une commande Annuler la transaction, la transaction d’origine redevient active.

La commande New-ItemProperty , qui fait partie de la transaction d’origine, se termine sans erreur et la transaction d’origine peut être effectuée à l’aide de la commande Complete-Transaction. Par conséquent, le registre est modifié.

Exemple 6 : Exécuter des commandes qui ne font pas partie d’une transaction

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

Cet exemple montre que les commandes soumises pendant qu’une transaction est en cours peuvent être incluses dans la transaction ou non incluses. Seules les commandes qui utilisent le paramètre UseTransaction font partie de la transaction.

Les commandes New-Item first et third utilisent le paramètre UseTransaction . Ces commandes font partie de la transaction. Étant donné que la deuxième commande New-Item n’utilise pas le paramètre UseTransaction, il ne fait pas partie de la transaction.

La première commande dir affiche l’effet. La deuxième commande New-Item est terminée immédiatement, mais le premier et le troisième commandes New-Item ne sont pas effectives tant que la transaction n’est pas validée.

La commande Complete-Transaction valide la transaction. Par conséquent, la deuxième commande dir indique que tous les nouveaux éléments sont ajoutés au Registre.

Exemple 7 : Restaurer une transaction qui ne se termine pas dans un délai spécifié

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

Cette commande utilise le paramètre Timeout de start-transaction pour démarrer une transaction qui doit être effectuée dans les deux minutes. Si la transaction n’est pas terminée lorsque le délai d’expiration expire, il est restauré automatiquement.

Lorsque le délai d’expiration expire, vous n’êtes pas averti, mais la propriété Status de l’objet de transaction est définie sur RolledBack et les commandes qui utilisent le paramètre use UseTransaction échouent.

Paramètres

-Confirm

Vous invite à confirmer avant d’exécuter l’applet de commande.

Type:SwitchParameter
Alias:cf
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Independent

Indique que cette applet de commande démarre une transaction indépendante de toutes les transactions en cours. Par défaut, si vous utilisez Start-Transaction pendant qu’une autre transaction est en cours, un nouvel abonné est ajouté à la transaction en cours. Ce paramètre a un effet uniquement lorsqu’une transaction est déjà en cours dans la session.

Par défaut, si vous utilisez start-transaction pendant qu’une transaction est en cours, l’objet de transaction existant est réutilisé et le nombre d’abonnés est incrémenté. L’effet ressemble beaucoup à la jointure de la transaction d’origine. Une commande Undo-Transaction restaure l’intégralité de la transaction. Pour terminer la transaction, vous devez entrer une commande Complete-Transaction pour chaque abonné. Étant donné que la plupart des transactions en cours en même temps sont liées, la valeur par défaut est suffisante pour la plupart des utilisations.

Si vous spécifiez le paramètre indépendant, cette applet de commande crée une transaction qui peut être terminée ou annulée sans affecter la transaction d’origine. Toutefois, étant donné qu’une seule transaction peut être active à la fois, vous devez terminer ou restaurer la nouvelle transaction avant de reprendre le travail sur la transaction d’origine.

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-RollbackPreference

Spécifie les conditions dans lesquelles une transaction est automatiquement restaurée. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • Erreur. La transaction est restaurée automatiquement si une erreur de fin ou de non-fin se produit.
  • TerminatingError. La transaction est restaurée automatiquement si une erreur de fin se produit.
  • Jamais. La transaction n’est jamais restaurée automatiquement.

La valeur par défaut est Error.

Type:RollbackSeverity
Valeurs acceptées:Error, TerminatingError, Never
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Timeout

Spécifie la durée maximale, en minutes, pendant laquelle la transaction est active. Lorsque le délai d’expiration expire, la transaction est automatiquement restaurée.

Par défaut, il n’existe aucun délai d’attente pour les transactions démarrées à la ligne de commande. Lorsque les transactions sont démarrées par un script, le délai d’attente par défaut est de 30 minutes.

Type:Int32
Alias:TimeoutMins
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-WhatIf

Affiche ce qui se passerait si l’applet de commande s’exécute. L’applet de commande n’est pas exécutée.

Type:SwitchParameter
Alias:wi
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

None

Vous ne pouvez pas diriger l’entrée vers cette applet de commande.

Sorties

None

Cette applet de commande ne génère aucune sortie.