Démarre une transaction.
Syntaxe
Start-Transaction [-Independent] [-RollbackPreference {<Error> | <TerminatingError> | <Never>}] [-Timeout <int>] [-Confirm] [-WhatIf] [<CommonParameters>]
Description
L'applet de commande Start-Transaction démarre une transaction, qui est une série de commandes gérées en bloc. Une transaction peut être exécutée (« validée ») ou elle peut être complètement annulée (« restaurée ») de manière à rétablir l'état d'origine des données modifiées par la transaction. Comme les commandes figurant dans une transaction sont gérées en bloc, toutes les commandes sont soit validées soit restaurées.
Les transactions sont automatiquement restaurées par défaut lorsqu'une commande figurant dans la transaction génère une erreur, mais 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 possèdent un paramètre UseTransaction. Pour exécuter des transactions dans un fournisseur, le fournisseur doit prendre en charge les transactions. Sous Windows Vista et les versions ultérieures de Windows, le fournisseur Registry de Windows PowerShell prend en charge les transactions. Vous pouvez également utiliser la classe Microsoft.PowerShell.Commands.Management.TransactedString pour inclure des expressions dans les transactions sur toute version de 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 (ni exécutée, ni annulée), 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.
L'applet de commande Start-Transaction fait partie d'un jeu d'applets de commande qui prennent en charge la fonctionnalité des transactions dans Windows PowerShell. Pour plus d'informations, consultez about_Transactions.
Paramètres
-Independent
Démarre une transaction qui est indépendante de toute transaction 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 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 transaction existant est réutilisé et le nombre d'abonnés est incrémenté. L'effet est similaire à la jointure de la transaction d'origine. Une commande Undo-Transaction restaure intégralement la transaction. Pour exécuter la transaction, vous devez entrer une commande Complete-Transaction 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 utilisez le paramètre Independent, une transaction pouvant être exécutée ou annulée sans affecter la transaction d'origine est créée. 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.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
Reuse the original transaction object. |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-RollbackPreference <RollbackSeverity>
Spécifie les conditions dans lesquelles une transaction est automatiquement restaurée. La valeur par défaut est « Error ».
Les valeurs valides sont :
-- Error : la transaction est automatiquement restaurée en cas d'erreur avec ou sans fin d'exécution. La valeur par défaut est « Error ».
-- Terminating error : la transaction est automatiquement restaurée en cas d'erreur avec fin d'exécution.
-- Never : la transaction n'est jamais restaurée automatiquement.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
Error |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Timeout <int>
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émarré au niveau de la ligne de commande pour les transactions. Lorsque les transactions sont démarrées par un script, le délai d'attente par défaut est de 30 minutes.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
No timeout (infinite) |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Confirm
Vous invite à confirmer l'exécution de la commande.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
|
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-WhatIf
Décrit le résultat que vous obtiendriez en exécutant la commande, sans réellement l'exécuter.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
|
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
<CommonParameters>
Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.
Entrées et sorties
Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.
|
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. |
Exemple 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 Description ----------- 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
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 Description ----------- Ces commandes démarrent une transaction, puis l'exécutent. Aucune modification n'est apportée au Registre tant que la commande Complete-Transaction n'a pas été utilisée.
Exemple 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
Description
-----------
Cet exemple illustre la modification de la valeur de paramètre RollbackPreference.
Dans le premier jeu de commandes, la commande Start-Transaction n'utilise pas le paramètre RollbackPreference. La valeur par défaut (« Error ») est par conséquent utilisée. Lorsqu'une erreur se produit dans une commande de transaction (le chemin d'accès spécifié n'existe pas), la transaction est automatiquement restaurée.
Dans le deuxième jeu de commandes, la commande Start-Transaction utilise le paramètre RollbackPreference avec la valeur « Never ». Lorsqu'une erreur se produit dans une commande de transaction, la transaction est encore active et peut être exécutée.
Comme la plupart des transactions doivent être exécutées sans erreur, la valeur par défaut du paramètre RollbackPreference est généralement préférée.
Exemple 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 Description ----------- Cet exemple illustre l'utilisation de la commande Start-Transaction pendant qu'une transaction est en cours. L'effet est similaire à la jointure de la transaction en cours. Même s'il s'agit d'une commande simplifiée, ce scénario se produit souvent 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 seconde commande Start-Transaction ajoute un nouvel abonné à la transaction. La commande Get-Transaction retourne alors une transaction avec un nombre d'abonnés ayant la valeur 2. La seconde commande New-Item fait partie de la même transaction. Aucune modification n'est apportée au Registre tant que la transaction n'a pas complètement été exécutée. Pour exécuter la transaction, vous devez entrer deux commandes Complete-Transaction, une pour chaque abonné. Si vous deviez restaurer la transaction à un moment ou un autre, la transaction serait intégralement restaurée pour les deux abonnés.
Exemple 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}
Description
-----------
Cet exemple illustre 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.
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 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 affiche l'objet transaction de la transaction active (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 Undo-Transaction, la transaction d'origine redevient active.
La commande New-ItemProperty, qui fait partie de la transaction d'origine, s'exécute sans erreur et la transaction d'origine peut être exécutée à l'aide de la commande Complete-Transaction. Le Registre est par conséquent modifié.
Exemple 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 {}
Description
-----------
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.
La première et la troisième commandes New-Item utilisent le paramètre UseTransaction. Ces commandes font partie de la transaction. Comme la deuxième commande New-Item n'utilise pas le paramètre UseTransaction, elle ne fait pas partie de la transaction.
La première commande « dir » montre l'effet. La deuxième commande New-Item s'est immédiatement exécutée, mais la première et la troisième commandes New-Item ne sont pas effectives tant que la transaction n'a pas été validée.
La commande Complete-Transaction valide la transaction. La deuxième commande « dir » montre que tous les nouveaux éléments ont été ajoutés au Registre.
Exemple 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 Description ----------- Cette commande utilise le paramètre Timeout de Start-Transaction pour démarrer une transaction qui doit être exécutée dans les deux minutes. Si la transaction n'est pas exécutée lorsque le délai d'attente expire, elle est automatiquement restaurée. Vous n'êtes pas informé de l'expiration du délai d'attente, mais la valeur RolledBack est affectée à la propriété Status de l'objet transaction et les commandes qui utilisent le paramètre UseTransaction échouent.
Voir aussi