Partager via

about_Trap

  • Article

Description courte

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 trap mot clé spécifie une liste d’instructions à exécuter lorsqu’une erreur de fin se produit. trap les instructions peuvent gérer les erreurs de fin de compte de la manière suivante :

  • Affichez l’erreur après le traitement du trap bloc d’instructions et l’exécution continue du script ou de la fonction contenant le trap. Il s’agit du comportement par défaut.

    Remarque

    Lorsque l’erreur de fin se produit dans un bloc de script 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 de script subordonné.

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

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

La liste des trap instructions peut inclure plusieurs conditions ou appels de fonction. Un trap peut écrire des journaux, des conditions de test 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 trap instruction se compose du trap mot clé, é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 interceptés trap .

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

Intercepter toutes les erreurs de fin

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 trap instruction qui gère l’erreur. Si une trap instruction est présente, PowerShell continue d’exécuter le script ou la commande dans l’instruction trap .

L’exemple suivant est une instruction minimale trap :

trap { 'Error found.' }

Cette trap instruction 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 : 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 line:3 char:5
+     nonsenseString
+     ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (nonsenseString:String) []
   , CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

L’exemple suivant inclut une trap instruction 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 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 : 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 line:3 char:5
+     nonsenseString
+     ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (nonsenseString:String) []
   , CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

Important

trap les instructions peuvent être définies n’importe où dans un bloc de script donné, mais s’appliquent toujours à toutes les instructions de ce bloc de script. Au moment de l’exécution, trap les instructions d’un bloc sont définies avant l’exécution d’autres instructions. En JavaScript, il s’agit d’un hoisting. Cela signifie que trap les instructions s’appliquent à toutes les instructions de ce bloc même si l’exécution n’a pas avancé au-delà du point auquel elles sont définies. Par exemple, la définition d’un trap script à la fin d’un script et la levée d’une erreur dans la première instruction déclenche toujours cette traperreur.

Intercepter des erreurs spécifiques

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

L’exemple suivant est une trap instruction 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 trap instruction affiche la Command error trapped chaîne. Après avoir exécuté la trap liste des instructions, 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 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 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 line:1 char:1
+ nonsenseString
+ ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (nonsenseString:String) []
   , CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

System.Management.Automation.CommandNotFoundException

Vous pouvez avoir plusieurs trap instructions dans un script. trap Une seule instruction 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 bloc de script actuel de l’exécution.

L’exemple de script suivant contient une erreur. Le script inclut une instruction générale trap 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 line: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 . L’instruction spécifique trap intercepte cette erreur de fin.

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

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 line:5 char:1
+ 1/$null}
+ ~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], RuntimeException
    + FullyQualifiedErrorId : RuntimeException

La tentative de division par zéro ne crée pas d’erreur CommandNotFoundException . L’autre trap instruction, qui intercepte toute erreur de fin, intercepte la division par zéro erreur.

Erreurs d’interception dans un bloc de script

Par défaut, lorsqu’une erreur de fin est levée, l’exécution transfère à l’instruction trap. Une fois le trap bloc 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!
Attempted to divide by zero.
At line:3 char:4
+    1/$x
+    ~~~~
    + CategoryInfo          : NotSpecified: (:) [], RuntimeException
    + FullyQualifiedErrorId : RuntimeException

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 du bloc de foreach script, exécute l’instruction try et se poursuit après le bloc de foreach script.

Intercepter les erreurs et l’étendue

Si une erreur de fin se produit dans le même bloc de script que l’instruction trap , PowerShell exécute la liste des instructions définies par le trap. L’exécution se poursuit à l’instruction après l’erreur. Si l’instruction trap se trouve dans un bloc de script différent de l’erreur, l’exécution se poursuit à l’instruction suivante qui se trouve dans le même bloc de script 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 trap instruction :

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

function1

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

An error:
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 line:3 char:5
+     NonsenseString
+     ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (NonsenseString:String) []
   , CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

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 Function1 terminé après l’instruction trap .

Comparez ce comportement à l’exemple suivant, qui a la même erreur et trap la même 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 Function2 fonction produit le résultat suivant :

An error:
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 line:2 char:5
+     NonsenseString
+     ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (NonsenseString:String) []
   , CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

Dans cet exemple, la function2 was completed commande 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 est en dehors de la fonction. PowerShell ne revient pas dans la fonction après l’exécution de l’instruction trap .

Attention

Lorsque plusieurs pièges sont définis pour la même condition d’erreur, le premier trap lexical (le plus élevé dans le bloc de script) est utilisé.

Dans l’exemple suivant, seules les trap whoops 1 exécutions sont exécutées.

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

Important

Une trap instruction est limitée à l’emplacement où elle se compile. Si vous avez une instruction à l’intérieur d’une trap fonction ou d’un script source de points, lorsque la fonction ou le script source point se termine, toutes les trap instructions à l’intérieur sont supprimées.

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

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

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

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

break_example

Error trapped
Attempted to divide by zero.
At line:6 char:5
+     1/$null
+     ~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], ParentContainsErrorR
   ecordException
    + FullyQualifiedErrorId : RuntimeException

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

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

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

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.

Notes

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

Voir aussi