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 Start-Transaction de commande 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. Comme les commandes figurant dans une transaction sont gérées en bloc, toutes les commandes sont soit validées soit 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 exécuter 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.

Start-Transaction l’applet de commande 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

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

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

Exemple 2 : Démarrer et terminer une transaction

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

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

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

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

Cet exemple illustre l’effet de la modification de la valeur du 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. Lorsqu’une erreur se produit dans une commande de transaction, la transaction est par conséquent encore active et peut être exécutée.

É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

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

Cet exemple montre l’effet de l’utilisation Start-Transaction pendant qu’une transaction est en cours. L’effet est similaire à la jonction 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 Start-Transaction commande démarre la transaction. La première New-Item commande fait partie de la transaction.

La deuxième Start-Transaction commande ajoute un nouvel abonné à la transaction. La Get-Transaction commande retourne maintenant une transaction avec un nombre d’abonnés de 2. La deuxième New-Item commande 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 Complete-Transaction commandes, 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

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}

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

Même si les transactions sont logiquement indépendantes, comme 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 jeu de commandes démarre une transaction. La New-Item commande fait partie de la première transaction.

Dans le deuxième jeu de commandes, la Start-Transaction commande utilise le paramètre Independent . La Get-Transaction commande suivante 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 Undo-Transaction commande, la transaction d’origine redevient active.

La New-ItemProperty commande, 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 Complete-Transaction commande. Le Registre est par conséquent modifié.

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

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

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

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

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

La Complete-Transaction commande valide la transaction. Par conséquent, la deuxième commande Get-ChildItem montre 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é

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

Cette commande utilise le paramètre Timeout pour Start-Transaction 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 transactionnel est définie sur RolledBack et les commandes qui utilisent le paramètre UseTransaction échouent.

Paramètres

-Confirm

Vous demande une confirmation 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 une autre transaction en cours, un nouvel abonné est ajouté à la transaction en cours. Ce paramètre prend uniquement effet 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 transactionnel existant est réutilisé et le nombre d’abonnés est incrémenté. L’effet est similaire à la jonction de la transaction d’origine. Une Undo-Transaction commande restaure l’intégralité de la transaction. Pour terminer la transaction, vous devez entrer une Complete-Transaction commande pour chaque abonné. Comme la plupart des transactions qui sont simultanément en cours sont liées, la valeur par défaut est suffisante dans la majorité des cas.

Si vous spécifiez le paramètre Independent , cette applet de commande crée une transaction qui peut être terminée ou annulée sans affecter la transaction d’origine. Comme une seule transaction peut être active à la fois, vous devez toutefois exécuter 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 valides pour ce paramètre sont :

  • Error 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.
  • Never 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 d’activité de la transaction (en minutes). Lorsque le délai d’attente expire, la transaction est automatiquement restaurée.

Par défaut, aucun délai d’attente n’est défini pour les transactions qui sont démarrées au niveau de 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

Montre ce qui se passe en cas d’exécution de l’applet de commande. 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 d'entrée vers cette applet de commande.

Sorties

None

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