à propos de Trap

Brève description

Décrit un mot-clé qui gère une erreur de fin.

Description longue

Une erreur de fin empêche l’exécution d’une instruction. Si PowerShell ne gère pas d’erreur de fin d’une certaine façon, PowerShell cesse également d’exécuter la fonction ou le script dans le pipeline actuel. Dans d’autres langages, tels que C#, les erreurs de fin sont appelées exceptions.

Le mot clé trap spécifie une liste d’instructions à exécuter lorsqu’une erreur de fin se produit. trap Les instructions peuvent gérer les erreurs de terminaison de la manière suivante :

• Affichez l’erreur après avoir traité le bloc d’instructions trap et continuez l'exécution du script ou de la fonction contenant le trap. Ce comportement est la valeur par défaut.

  Remarque

  Lorsque l’erreur de fin se produit dans un bloc d’instructions subordonné, tel qu’une instruction ou foreach une if boucle, les instructions du trap bloc sont exécutées et l’exécution se poursuit à l’instruction suivante en dehors du bloc subordonné.

• Affichez l’erreur et abandonnez l’exécution du script ou de la fonction contenant le trap à l’aide de break dans l’instruction trap.

• Silence l’erreur, mais continuer l’exécution du script ou de la fonction contenant le trap à l’aide de continue dans l’instruction trap.

La liste des instructions du trap peut inclure plusieurs conditions ou appels de fonction. Un trap peut écrire des logs, tester des conditions, ou même exécuter un autre programme.

Syntaxe

L’instruction trap a la syntaxe suivante :

trap [[<error type>]] {<statement list>}

L’instruction trap inclut une liste d’instructions à exécuter lorsqu’une erreur de fin se produit. Une instruction trap se compose du mot clé trap, éventuellement suivi d’une expression de type et du bloc d’instructions contenant la liste des instructions à exécuter lorsqu’une erreur est interceptée. L’expression de type affine les types d’erreurs que les trap interceptent.

Un script ou une commande peut avoir plusieurs instructions trap. trap les instructions peuvent apparaître n'importe où dans le script ou la commande.

Trappe de toutes les erreurs de terminaison

Lorsqu’une erreur de fin se produit qui n’est pas gérée d’une autre manière dans un script ou une commande, PowerShell recherche une instruction trap qui gère l’erreur. Si une instruction trap est présente, PowerShell continue d’exécuter le script ou la commande dans l’instruction trap.

L’exemple suivant est une instruction trap minimale :

trap { 'Error found.' }

Cette instruction trap intercepte toute erreur de fin.

Dans l’exemple suivant, la fonction inclut une chaîne nonsense qui provoque une erreur d’exécution.

function TrapTest {
    trap { 'Error found.' }
    nonsenseString
}

TrapTest

L’exécution de cette fonction retourne la sortie suivante :

Error found.
nonsenseString:
Line |
   3 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

L’exemple suivant inclut une trap instruction qui affiche l’erreur à l’aide de la variable automatique ou $PSItem de la $_ variable :

function TrapTest {
    trap { "Error found: $_" }
    nonsenseString
}

TrapTest

L’exécution de cette version de la fonction retourne la sortie suivante :

Error found: The term 'nonsenseString' is not recognized as the name of a
cmdlet, function, script file, or operable program. Check the spelling of
the name, or if a path was included, verify that the path is correct and
try again.
nonsenseString:
Line |
   3 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Trappe d'erreurs spécifiques

Un script ou une commande peut avoir plusieurs instructions trap. Une trap peut être définie pour gérer des erreurs spécifiques.

L’exemple suivant est une instruction trap qui intercepte l’erreur spécifique CommandNotFoundException:

trap [System.Management.Automation.CommandNotFoundException] {
    'Command error trapped'
}

Lorsqu’une fonction ou un script rencontre une chaîne qui ne correspond pas à une commande connue, cette instruction trap affiche la chaîne Command error trapped. Après avoir exécuté la liste des instructions trap, PowerShell écrit l’objet d’erreur dans le flux d’erreurs, puis poursuit le script.

PowerShell utilise des types d’exceptions .NET. L’exemple suivant spécifie le type d’erreur System.Exception :

trap [System.Exception] { 'An error trapped' }

Le type d’erreur CommandNotFoundException hérite du type de System.Exception. Cette instruction intercepte les erreurs générées par des commandes inconnues. Il intercepte également d’autres types d’erreurs.

Vous pouvez trouver le type d’exception pour une erreur en inspectant l’objet d’erreur. L’exemple suivant montre comment obtenir le nom complet de l’exception pour la dernière erreur dans une session :

nonsenseString
$Error[0].Exception.GetType().FullName

nonsenseString: The term 'nonsenseString' is not recognized as a name of a
cmdlet, function, script file, or executable program. Check the spelling
of the name, or if a path was included, verify that the path is correct
and try again.

System.Management.Automation.CommandNotFoundException

Vous pouvez avoir plusieurs instructions trap dans un script. Une seule instruction trap peut intercepter chaque type d’erreur. Lorsqu’une erreur de fin se produit, PowerShell recherche la trap correspondance la plus spécifique, en commençant par le scriptblock actuel de l’exécution.

L’exemple de script suivant contient une erreur. Le script inclut une instruction trap générale qui intercepte toute erreur de fin et une instruction trap spécifique qui spécifie le type CommandNotFoundException.

trap { 'Other terminating error trapped' }
trap [System.Management.Automation.CommandNotFoundException] {
  'Command error trapped'
}
nonsenseString

L’exécution de ce script produit le résultat suivant :

Command error trapped
nonsenseString:
Line |
   5 |      nonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'nonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Étant donné que PowerShell ne reconnaît pas nonsenseString en tant qu’applet de commande ou autre élément, il retourne une erreur CommandNotFoundException. L’instruction trap spécifique intercepte cette erreur de fin.

L’exemple de script suivant contient les mêmes instructions trap avec une erreur différente :

trap { 'Other terminating error trapped' }
trap [System.Management.Automation.CommandNotFoundException] {
    'Command error trapped'
}
1/$null

L’exécution de ce script produit le résultat suivant :

Other terminating error trapped
RuntimeException:
Line |
   5 |  1/$null
     |  ~~~~~~~
     | Attempted to divide by zero.

La tentative de division par zéro ne crée pas d’erreur CommandNotFoundException. L'autre instruction trap, qui piège toute erreur de terminaison, piège l'erreur de division par zéro.

Intercepter les erreurs dans un scriptblock

Par défaut, lorsqu'une erreur de fin est déclenchée, l'exécution passe à l'instruction trap. Une fois le bloc trap exécuté, le contrôle retourne au bloc d’instruction suivant après l’emplacement de l’erreur.

Par exemple, lorsqu’une erreur de fin se produit dans une foreach instruction, l’instruction trap est exécutée et l’exécution se poursuit à l’instruction suivante après le foreach bloc, et non dans le foreach bloc.

trap { 'An error occurred!'}
foreach ($x in 3..-1) {
       "1/$x = "
       "`t$(1/$x)"
}
'after loop'

1/3 =
        0.333333333333333
1/2 =
        0.5
1/1 =
        1
1/0 =
An error occurred!
RuntimeException:
Line |
   4 |         "`t$(1/$x)"
     |              ~~~~
     | Attempted to divide by zero.
after loop

Dans la sortie, vous pouvez voir que les boucles continuent jusqu’à la dernière itération. Lorsque le script tente de diviser 1 par 0, PowerShell génère une erreur de fin. Le script ignore le reste de l’instruction foreach , exécute l’instruction try et se poursuit après l’instruction foreach .

Erreurs de trappe et portée

Si une erreur de fin se produit dans le même scriptblock que l’instruction trap , PowerShell exécute la liste des instructions définies par le trap. L'exécution se poursuit à l'instruction qui suit l'erreur. Si l’instruction trap se trouve dans un scriptblock différent de l’erreur, l’exécution se poursuit à l’instruction suivante qui se trouve dans le même scriptblock que l’instruction trap .

Par exemple, si une erreur se produit dans une fonction et que l’instruction trap se trouve dans la fonction, le script se poursuit à l’instruction suivante. Le script suivant contient une erreur et une instruction trap :

function function1 {
    trap { 'An error: ' }
    NonsenseString
    'function1 was completed'
}

function1

L’exécution de ce script produit le résultat suivant :

An error:
NonsenseString:
Line |
   3 |      NonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'NonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.
function1 was completed

L’instruction trap dans la fonction intercepte l’erreur. Après avoir affiché le message, PowerShell reprend l’exécution de la fonction. Notez que Function1 s'est terminé après l'instruction trap.

Comparez ce comportement à l’exemple suivant, qui a la même erreur et trap instruction. Dans cet exemple, l’instruction trap se produit en dehors de la fonction :

function function2 {
    NonsenseString
    'function2 was completed'
}

trap { 'An error:' }

function2

L’exécution de la fonction Function2 produit le résultat suivant :

An error:
NonsenseString:
Line |
   2 |      NonsenseString
     |      ~~~~~~~~~~~~~~
     | The term 'NonsenseString' is not recognized as a name of a cmdlet,
function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the
path is correct and try again.

Dans cet exemple, la commande function2 was completed n’a pas été exécutée. Dans les deux exemples, l’erreur de fin se produit dans la fonction. Dans cet exemple, toutefois, l’instruction trap se trouve en dehors de la fonction. PowerShell ne revient pas dans la fonction après l’exécution de l’instruction trap.

Dans l'exemple suivant, seule l'instruction trap avec whoops 1 s'exécute.

Remove-Item -ErrorAction Stop ThisFileDoesNotExist
trap { 'whoops 1'; continue }
trap { 'whoops 2'; continue }

Utilisation des mots clés d’arrêt et de poursuite

Vous pouvez utiliser les mots clés break et continue dans une instruction trap pour déterminer si un script ou une commande continue de s’exécuter après une erreur de fin.

Si vous incluez une instruction break dans une liste d’instructions trap, PowerShell arrête la fonction ou le script. L’exemple de fonction suivant utilise le mot clé break dans une instruction trap :

function break_example {
    trap {
        'Error trapped'
        break
    }
    1/$null
    'Function completed.'
}

break_example

Error trapped
ParentContainsErrorRecordException:
Line |
   6 |      1/$null
     |      ~~~~~~~
     | Attempted to divide by zero.

Étant donné que l’instruction trap incluait le mot clé break, la fonction ne continue pas à s’exécuter et la ligne Function completed n’est pas exécutée.

Si vous incluez un mot clé continue dans une instruction trap, PowerShell reprend après l’instruction qui a provoqué l’erreur, comme cela se passerait sans break ou continue. Toutefois, avec le mot clé continue, PowerShell n’écrit pas d’erreur dans le flux d’erreurs.

L’exemple de fonction suivant utilise le mot clé continue dans une instruction trap :

function ContinueExample {
    trap {
        'Error trapped'
        continue
    }
    foreach ($x in 3..-1) {
       "1/$x = "
       "`t$(1/$x)"
    }
    'End of function'
}

ContinueExample

1/3 =
        0.333333333333333
1/2 =
        0.5
1/1 =
        1
1/0 =
Error trapped
End of function

La fonction reprend une fois l’erreur interceptée et l’instruction End of function s’exécute. Aucune erreur n’est écrite dans le flux d’erreurs.

Remarques

trap les instructions fournissent un moyen de s’assurer que toutes les erreurs de fin dans un scriptblock sont gérées. Pour une gestion des erreurs plus précise, utilisez try/catch des blocs où les pièges sont définis à l’aide catch d’instructions. Les instructions catch s’appliquent uniquement au code à l’intérieur de l’instruction try associée. Pour plus d'informations, voir about_Try_Catch_Finally.

Voir aussi

• about_Break
• about_Continue
• about_Scopes
• about_Throw
• about_Try_Catch_Finally