À 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 une erreur de fin d’une manière ou d’une autre, PowerShell arrête é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. Les instructions Trap gèrent les erreurs de fin et permettent à l’exécution du script ou de la fonction de se poursuivre au lieu de s’arrêter.

Les instructions pièges peuvent également être plus complexes. La liste d’instructions de l’interruption peut inclure plusieurs conditions ou appels de fonction. Une interruption peut écrire des journaux, tester des conditions ou même exécuter un autre programme.

Syntaxe

La syntaxe de l’instruction Trap est la suivante :

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

L’instruction Trap comprend 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 détectés par l’interruption.

Un script ou une commande peut avoir plusieurs instructions Trap. Les instructions Trap 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 très simple :

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 renvoie les éléments suivants :

Error found.

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

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

TrapTest

L’exécution de cette version de la fonction renvoie ce qui suit :

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 then try
again.

Important

Les instructions Trap peuvent être définies n’importe où dans une portée donnée, mais s’appliquent toujours à toutes les instructions de cette portée. Au moment de l’exécution, les interruptions d’un bloc sont définies avant l’exécution de toute autre instruction. En JavaScript, cette méthode est connue sous le nom de hoisting. Cela signifie que les interruptions s’appliquent à toutes les instructions de ce bloc, même si l’exécution n’a pas dépassé le point où elles sont définies. Par exemple, la définition d’un piège à la fin d’un script et le déclenchement d’une erreur dans la première instruction déclenchent toujours ce piège.

Trappe d'erreurs spécifiques

Un script ou une commande peut avoir plusieurs instructions Trap. Des interruptions peuvent être définies 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 « Erreur de commande piégée ». 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 les types d’exception Microsoft .NET Framework. 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 une erreur créée par une commande inconnue. Il intercepte également d’autres types d’erreurs.

Vous pouvez avoir plusieurs instructions Trap dans un script. Chaque type d’erreur ne peut être intercepté que par une seule instruction Trap. Lorsqu’une erreur de fin se produit, PowerShell recherche l’interruption avec la correspondance la plus spécifique, en commençant par l’étendue d’exécution actuelle.

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 spécifique Trap 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 : 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.
At C:\temp\test\traptest.ps1:5 char:1
+ nonsenseString
+ ~~~~~~~~~~~~~~
+ CategoryInfo          : ObjectNotFound: (nonsenseString:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException

Étant donné que PowerShell ne reconnaît pas « nonsenseString » en tant qu’applet de commande ou autre élément, il retourne une erreur CommandNotFoundException . Cette erreur de fin est interceptée par l’instruction Trap spécifique.

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
Attempted to divide by zero.
At C:\temp\test\traptest.ps1:5 char:1
+ 1/$null
+ ~~~~~~~
+ CategoryInfo          : NotSpecified: (:) [], RuntimeException
+ FullyQualifiedErrorId : RuntimeException

La tentative de division par zéro ne crée pas d’erreur CommandNotFoundException . Au lieu de cela, cette erreur est interceptée par l’autre instruction Trap, qui intercepte toute erreur de fin.

Erreurs de trappe et portée

Si une erreur de fin se produit dans la même étendue que l’instruction Trap, PowerShell exécute la liste des instructions définies par l’interruption. L'exécution se poursuit à l'instruction qui suit l'erreur. Si l’instruction Trap se trouve dans une portée différente de celle de l’erreur, l’exécution se poursuit à l’instruction suivante qui se trouve dans la même étendue 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 continue à l’instruction suivante. Le script suivant contient une erreur et une instruction trap :

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

Plus loin dans le script, l’exécution de la fonction Function1 produit le résultat suivant :

function1
An error:
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
then try again.
At C:\PS>TestScript1.ps1:3 char:19
+     NonsenseString <<<<

function1 was completed

L’instruction Trap de la fonction intercepte l’erreur. Après avoir affiché le message, PowerShell reprend l’exécution de la fonction. Notez que cela Function1 a été terminé.

Comparez cela avec l’exemple suivant, qui contient la même erreur et Trap la même déclaration. 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:
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
then try again.
At C:\PS>TestScript2.ps1:4 char:19
+     NonsenseString <<<<

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, cependant, 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.

Avertissement

Lorsque plusieurs interruptions sont définies pour la même condition d’erreur, la première interruption définie lexicalement (la plus élevée dans l’étendue) est utilisée.

Dans l’exemple suivant, seul l’interruption avec « whoops 1 » est exécutée.

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

À l’aide des `break` mots-clés et `continue`

Vous pouvez utiliser les Break mots-clés et dans Continue 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 Break instruction dans une liste d’instructions Trap, PowerShell arrête la fonction ou le script. L’exemple de fonction suivant utilise le Break mot-clé dans une instruction Trap :

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

break_example

Error trapped
Attempted to divide by zero.
At line:4 char:7

Étant donné que l’instruction Trap incluait le mot-clé Break , l’exécution de la fonction ne se poursuit pas et celle de la ligne « Fonction terminée » n’est pas exécutée.

Si vous incluez une Continue instruction dans une instruction Trap, PowerShell reprend après l’instruction à l’origine de l’erreur, comme il le ferait sans Break ou Continue. Avec le Continue mot clé, cependant, 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 continue_example {
    trap {
        "Error trapped"
        continue
    }
    1/$null
    "Function completed."
}

continue_example

Error trapped
Function completed.

La fonction reprend une fois l’erreur interceptée et l’instruction « Fonction terminée » s’exécute. Aucune erreur n’est écrite dans le flux d’erreurs.

Remarques

Les instructions Trap offrent un moyen simple de s’assurer que toutes les erreurs de fin d’une étendue sont traitées. Pour une gestion des erreurs plus granulaire, utilisez les blocs try/catch où les pièges sont définis à l’aide d’instructions Catch. 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.